Jump to content

Developer Documentation

core/IpAddresses

What it is

IpAddresses extensions allow your application to tie into the AdminCP and ModeratorCP IP address lookup areas to show when an IP address has been registered in your application, or all IP addresses used by a specific member. If your application does not store any IP addresses, you will not need to use this extension. If your application stores IP addresses outside of Content Item classes it is recommended that you create one or more IpAddresses extensions to allow administrators better visibility over site usage.

Note that if your application has Content Items and you have properly defined your ContentRouter extension, you do not need to create IpAddresses extensions for those content item classes as they will automatically be searched. This extension can be used for supplemental storage of IP addresses, however (for instance, Downloads stores the IP address for each downloader and uses an IpAddresses extension to allow administrators to search these records).

How to use

The extension, when created, has 4 methods you will need to set.

    /**
     * Supported in the ACP IP address lookup tool?
     *
     * @return    bool
     * @note    If the method does not exist in an extension, the result is presumed to be TRUE
     */
    public function supportedInAcp()
    {
        return TRUE;
    }

    /**
     * Supported in the ModCP IP address lookup tool?
     *
     * @return    bool
     * @note    If the method does not exist in an extension, the result is presumed to be TRUE
     */
    public function supportedInModCp()
    {
        return TRUE;
    }

The supportedInAcp() and supportedInModCp() methods are self-explanatory: they return a boolean flag to indicate if the extension should be loaded and checked in the AdminCP and ModeratorCP respectively. Some extensions may not wish to show data in one or the other area. For example, Commerce purchases cannot be managed by moderators and is considered more sensitive data, so IP addresses associated with commerce products are only available to look up in the AdminCP.

    /** 
     * Find Records by IP
     *
     * @param    string            $ip            The IP Address
     * @param    \IPS\Http\Url    $baseUrl    URL table will be displayed on or NULL to return a count
     * @return    \IPS\Helpers\Table|int|null
     */
    public function findByIp( $ip, \IPS\Http\Url $baseUrl = NULL )
    {
        /* Return count */
        if ( $baseUrl === NULL )
        {
            return \IPS\Db::i()->select( 'COUNT(*)', 'database_table_name', array( "ip_address LIKE ?", $ip ) )->first();
        }
        
        /* Init Table */
        // Replace database_table_name with the database table
        $table = new \IPS\Helpers\Table\Db( 'database_table_name', $baseUrl, array( "ip_address LIKE ?", $ip ) );
        
        /* Return */
        return (string) $table;
    }

The findByIp() method expects to receive an IP address (or partial IP address) and return an instance of \IPS\Helpers\Table that will be output. Most commonly you will us the \IPS\Helpers\Table\Db method for this purpose. This automatically implements pagination and so on, while allowing you to control which columns are shown in the lookups and how they are formatted.

    /**
     * Find IPs by Member
     *
     * @code
         return array(
             '::1' => array(
                 'ip'        => '::1'// string (IP Address)
                 'count'        => ...    // int (number of times this member has used this IP)
                 'first'        => ...     // int (timestamp of first use)
                 'last'        => ...     // int (timestamp of most recent use)
             ),
             ...
         );
     * @endcode
     * @param    \IPS\Member    $member    The member
     * @return    array|NULL
     */
    public function findByMember( $member )
    {
        return array();
    }

The findByMember() method accepts an \IPS\Member object and should subsequently return an array formatted as keys being the IP addresses found (within your application) and the values being arrays with keys 'ip' (the IP address again), 'count' (the number of instances the IP address was found for this member), 'first' (the timestamp of the first found instance of this IP address used by this member) and 'last' (the timestamp of the last time this IP address was used by this member).

 


  Report Document


×
×
  • Create New...