Jump to content


  • We are moving our Documentation to our new Guides area.

    As articles are moved they will be deleted. Please start following the new guides. We look forward to publishing all our new guides soon!

  • Introduction to Active Records (*)

    Most of the classes you will work with while using Nodes and Content Items will extend \IPS\Patterns\ActiveRecord. Objects of this class represent a row in the database table. It is important that you use the methods provided by this class rather than calling the database directly, as when you add additional features to your content item, the methods will perform more complicated tasks.

    static load( int $id )

    A factory method that retrieves record from the database and returns an object of your Content Item class.

    Results are cached so if you load the same item twice, a second database query will not be made and both calls will return the same object (the same object by reference - not a copy of the object).


    $item = YourClass::load( 1 );

    static constructFromData( array $data )

    If, for some reason, you do need to select data directly from the database (for example, if you want to get the most recent record), and you have an array containing a row from the database, the constructFromData method allows you to create an object out of that data, without having to call load which would make another (unnecessary) database query.


    $item = YourClass::constructFromData( \IPS\Db::i()->select(...)-
    >first() );

    __get( mixed $key ) __set( mixed $key, mixed $value )
    Though you do not call these methods directly - magic getters and setters allow you to get

    and set the values in the database row.

    A static property, $databasePrefix, can be set if all the columns in your database table start with the same prefix, then you do not need to included that.

    For example, let’s say your database table looks like this:

















    You would set $databasePrefix:

    static $databasePrefix = 'item_';

    You would load the first row like so (it will automatically look for columns called “id”):

    $item = YourClass::load( 1 );

    And could then get the title like so:

    echo $item->title;

    If you want to override the behaviour for any particular column (for example, if you have a database column which stores a timestamp, and you want the getter/setter to handle \IPS \DateTime objects) you can define methods called get_<key> and set_<key>. In these methods the $_data property stores the raw values. For example:

    public function get_date() {
         return \IPS\DateTime::ts( $this->_data[‘date’] );


    public function set_date( $value ) {
         $this->data[‘date’] = $value->getTimestamp();



    After changing any properties, you must call the save method to actually save those changes to the database.


    $item = YourClass::load( 1 );
    $item->title = 'New Title';


    The delete method deletes the item from the database.


    $item = YourClass::load( 1 );



    A magic method exists to automatically adjust the primary key when you clone an item;


    $item = YourClass::load( 1 );
    $copy = clone $item;
    echo $item->id; // 4

    Bitwise Flags

    The ActiveRecord class provides special features to facilitate bitwise operation, allowing you to use one INT column in your database to store multiple binary values.

    To do this, you can define a static $bitOptions property in your class like so:

         public static $bitOptions = array(
              'bitwise_column' => array(
                   'bitwise_column' => array(

    ), ),


    => 1,
    => 2,
    => 4,

    In this example, there is a database column (bitwise_column) storing bitwise data (if you needed to store more values than could be stored in a single INT field, you could add additional columns). This column stores 3 boolean values (property_1, property_2 and property_3). When defining properties, you must define them with the numeric value they will be represented by, so the number must double each time (1, 2, 4, 8, 16, etc.).

    The ActiveRecord will automatically provide an \IPS\Patterns\Bitwise object for this column, which implements \ArrayAccess. You can get and set values as if it was an array:

    /* Getting a value */
    if ( $object->bitwise_column[‘property_1’] ) {

    // . . . }

    /* Setting a value */
    $object->bitwise_column[‘property_2’] = FALSE;

    /* Getting database rows */
    $rowsWithPropery1AsTrue = \IPS\Db::i()->select( ‘*’, ‘table’, \IPS \Db::i()->bitwiseWhere( \IPS\YourClass:: $bitOptions['bitwise_column'], 'property_1' ));


    Class Definition

    When you create classes ion the IPS Community Suite, you will always define your class with a preceding underscore. Even though you do this, you do not call it with the preceding underscore. This is a technicality of how autoloading works.


    There is a method, loadAndCheckPerms( int $id ) which is common to all the classes worked with in this document, though it is not part of \IPS\Patterns\ActiveRecord.

    By default, it behaves the same as the load( int $id ) method provided by \IPS \Patterns\ActiveRecord, however, as you add additional features, it will check appropriate permissions. For example, once you implement front-end permissions, it will throw an OutOfRangeException if the currently logged in user does not have permission to view the object. Similarly, once you implement hiding content, it will throw an OutOfRangeException if used to load a hidden object and the currently logged in user does not have permission to view hidden objects.

    You should therefore always use this method over load( int $id ) when loading nodes, content items, comments and reviews on the front-end, or in any code called from the front-end. 

    User Feedback

    Recommended Comments

    There are no comments to display.

  • Create New...

Important Information

We use technologies, such as cookies, to customise content and advertising, to provide social media features and to analyse traffic to the site. We also share information about your use of our site with our trusted social media, advertising and analytics partners. See more about cookies and our Privacy Policy