Open menu Close menu

PHP API

LOGman exposes a convinient API endopoint through the activity controller for adding activities without the need of a LOGman plugin. This allows developers to integrate LOGman with other extensions by making activity logging calls within the component.

Adding an activity record is as simple as making the following call: 

<?php
Koowa::getObject('com://admin/logman.controller.activity')->log($data);

Variables

The $data variable is a PHP array containing the activity data to log. This array may contain the following keys (value within parenthesis corresponds to the default value meaning that the key is optional):

  • result: The result of the action, e.g. added, deleted, edited, etc.
  • verb: The verb or action that was executed, e.g. add, delete, edit, etc.
  • application ('admin' or 'site' depending on the application running during the call): The application where the action is executed. Possible values are 'admin' and 'site'.
  • actor (current logged user ID): The actor which is the user executing the action. The value must be a user ID.
  • object
    • package: The package of the component, e.g. foo for com_foo.
    • type: The type of the object on which the action is executed, e.g. article, document, file, category, etc.
    • id: The object row ID as stored in the database table.
    • name: The object name. Most frequently the entity title or name is used here.
    • table (pluralized value set in type): The name of the table contaning the entities representing the activity objects, e.g. content for article, categories for category, etc.
    • column ('id'): The identity column name of the entities table representing actvitity objects.
    • url (null): Activity URL overrides.

If we would like to add an activity within com_foo component when deleting a bar item from the foo_bars table with ID=1, we would just need to make the following call: 

<?php
Koowa::getObject('com://admin/logman.controller.activity')
    ->log([
        'result' => 'deleted',
        'verb' => 'delete',
        'object' => [
            'package' => 'foo',
            'type' => 'bar',
            'id' => 1,
            'name' => 'Awesome bar'
            ]
        ]
    );

The above call will add a log entry into LOGman about the bar item that got deleted.

AS IS item links in activity messages created with the endpoint API will be only available on backend activity streams. The URL template that gets used by default is the one used for Joomla's core components, i.e. option=com_foo&task=bar.edit&id=1.

It is possible though to provide custom URLs for backend and/or frontend streams. For this end you just need to provide the URLs when logging the activity. 

<?php
Koowa::getObject('com://admin/logman.controller.activity')
    ->log([
        'result' => 'added',
        'verb' => 'add',
        'object' => [
            'package' => 'foo',
            'type' => 'bar',
            'id' => 1,
            'name' => 'Awesome bar',
            'url' => [
                'admin' => 'option=com_foo&view=bars&id=1',
                'site' => 'option=com_foo&view=bars&id=1&Itemid=5'
                ]
            ]
        ]
    );

Here we have provided both site and admin URLs. We could just have provided one or the other. The admin URL will get used on backend streams while site will get used for frontend streams. For site URLs there are two checks that LOGman will perform when rendering these links. If an Itemid is set, LOGman will check that the menu item exists and that this menu item is accessible by the current logged user. If this is not the case, then the site URL will get ignored.

LOGman makes a lookup search to see if activity objects still exist so as to decide if it should link them or not while rendering activity streams. You probably already noticed that when an article is deleted all activities related to that article no longer provide a link to it as it does not exist anymore. As seen above, the object data key contains two additional keys (table and column) for letting LOGman know how to perform the activity object search in the database. If the default values do not apply make sure to provide these during the log call so that the search may be properly executed. As an example, if the bars table is named foo_bars and the identitity column on this table is bar_id, then the log call becomes: 

<?php
Koowa::getObject('com://admin/logman.controller.activity')
    ->log([
        'result' => 'added',
        'verb' => 'add',
        'object' => [
            'package' => 'foo',
            'type' => 'bar',
            'id' => 1,
            'name' => 'Awesome bar',
            'table' => 'foo_bars',
            'column' => 'bar_id'
            ]
        ]
    );

Activity messages

The activity message format that gets used by default is: 

{actor} {action} {object.type} title {object}

which translates as follows when rendered in activity streams: 

John deleted the bar with the title Awesome bar

The default format for your activity message may be overridden by passing an additional key to object when making the log call: 

<?php
Koowa::getObject('com://admin/logman.controller.activity')
    ->log([
        'result' => 'deleted',
        'verb' => 'delete',
        'format' => '{actor} {action} {object.type} name {object}',
        'object' => []
            'package' => 'foo',
            'type' => 'bar',
            'id' => 1,
            'name' => 'Awesome foo'
            ]
        ]
    );

Here we have specified a format string in the format key of the object. This string will act as a template for rendering this activity and will now read as (note the name part): 

John deleted the bar with the name Awesome bar

{actor}, {action}, {object.type} and {object} are variables that will resolve to the name of the actor, the resulting action, the type of the activity object and the object name as provided when logging the activity record. These are the only variables that are available for constructing activity messages that were logged using the endpoint API. If you need additional flexibility when it comes to rendering activity messages you should then consider building a LOGman plugin instead.

To override an activity message we could add the following as a translation override: 

KLS_ACTOR_ACTION_BAR_NAME_OBJECT="{actor} {action} the small {object.type} called {object}"

which will result in the following activity message: 

John deleted the small bar called Awesome bar

You'll find more information about overrides and the activity translation engine here.