4.A. Reference: Events

The following events are used throughout the system and is encouraged that you try to use these before deciding to write your own events.

4.A.1. System Model Events

Model events are used to manage the objects defined by schemas.

4.A.1.1. system-model-create

Inserts a row into the database

Parameters: system-model-create
Name Validation Description Example
schema required Name of the schema profile
[fields] required Fields defined in the provided schema {"profile_name": "John Doe"}
PHP Example: system-model-create
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']
        ->setStage('schema', 'profile')
        ->setStage('profile_name', 'John Doe');

    $this->trigger('system-model-create', $payload['request'], $payload['response']);
});
CLI Example: system-model-create
$ bin/cradle system-model-create schema=profile profile_name="John Doe"
Example Response: system-model-create
{
    "error": false,
    "results": {
        "profile_id": 1,
        "profile_name": "John Doe",
        "profile_active": 1,
        "profile_created": "2019-01-01 00:00:00"
        "profile_updated": "2019-01-01 00:00:00"
    }
}

4.A.1.2. system-model-detail

Retrieves a row from the database

Parameters: system-model-detail
Name Validation Description Example
schema required Name of the schema profile
[unique field] required The primary ID or a unique field defined in the provided schema {"profile_id": 1}
PHP Example: system-model-detail
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']
        ->setStage('schema', 'profile')
        ->setStage('profile_id', 1);

    $this->trigger('system-model-detail', $payload['request'], $payload['response']);
});
CLI Example: system-model-detail
$ bin/cradle system-model-detail schema=profile profile_id=1
Example Response: system-model-detail
{
    "error": false,
    "results": {
        "profile_id": 1,
        "profile_name": "John Doe",
        "profile_active": 1,
        "profile_created": "2019-01-01 00:00:00"
        "profile_updated": "2019-01-01 00:00:00"
    }
}

4.A.1.3. system-model-remove

Removes a row from the database. If an active field is not provided in the provided schema, this will permanently remove the row.

Parameters: system-model-remove
Name Validation Description Example
schema required Name of the schema profile
[unique field] required The primary ID or a unique field defined in the provided schema {"profile_id": 1}
PHP Example: system-model-remove
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']
        ->setStage('schema', 'profile')
        ->setStage('profile_id', 1);

    $this->trigger('system-model-remove', $payload['request'], $payload['response']);
});
CLI Example: system-model-remove
$ bin/cradle system-model-remove schema=profile profile_id=1
Example Response: system-model-remove
{
    "error": false,
    "results": {
        "profile_id": 1,
        "profile_name": "John Doe",
        "profile_active": 0,
        "profile_created": "2019-01-01 00:00:00"
        "profile_updated": "2019-01-01 00:00:00"
    }
}

4.A.1.4. system-model-restore

Restores a row from the database. If an active field is not provided in the provided schema, this will event will not work.

Parameters: system-model-restore
Name Validation Description Example
schema required Name of the schema profile
[unique field] required The primary ID or a unique field defined in the provided schema {"profile_id": 1}
PHP Example: system-model-restore
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']
        ->setStage('schema', 'profile')
        ->setStage('profile_id', 1);

    $this->trigger('system-model-restore', $payload['request'], $payload['response']);
});
CLI Example: system-model-restore
$ bin/cradle system-model-restore schema=profile profile_id=1
Example Response: system-model-restore
{
    "error": false,
    "results": {
        "profile_id": 1,
        "profile_name": "John Doe",
        "profile_active": 1,
        "profile_created": "2019-01-01 00:00:00"
        "profile_updated": "2019-01-01 00:00:00"
    }
}

Searches for rows in the database.

Name Validation Description Example
schema required Name of the schema profile
q optional Search Term John
filter optional Exact match given the column/s {"filters": {"profile_name": "John Doe"}}
in optional Range match given the column/s {"in": {"profile_name": ["John","Jane"]}}
like optional Partial match given the column/s {"like": {"profile_name": John}}
span optional Number ranges {"span": {"product_price": [0,100]}}
start optional (default:0) The starting index 1
range optional (default:50) Up to how many rows to return 25 
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']
        ->setStage('schema', 'profile')
        ->setStage('q', 'John')
        ->setStage('filter', 'profile_name', 'John Doe')
        ->setStage('like', 'profile_name', 'John')
        ->setStage('in', 'profile_name', ['John Doe', 'Jane Doe'])
        ->setStage('start', 0)
        ->setStage('range', 10);

    $this->trigger('system-model-search', $payload['request'], $payload['response']);
});

$ bin/cradle system-model-search schema=profile q=John start=0 range=10 __json='{"filter":{"profile_name":"John Doe"},"in":{"profile_name":["John Doe", "Jane Doe"]},"like":{"profile_name":"John"}}'

$ bin/cradle system-model-search schema=profile q=John start=0 range=10 __query='filter[profile_name]=John+Doe&in[profile_name][]=John+Doe&in[profile_name][]=Jane+Doe&like[profile_name]=John'

{
    "error":false,
    "results": {
        "rows": [
            {
                "profile_id": 1,
                "profile_name": "John Doe",
                "profile_active": 1,
                "profile_created": "2019-01-20 06:43:42",
                "profile_updated": "2019-01-20 06:43:42"
            },
            {
                "profile_id": 2,
                "profile_name": "John Doe",
                "profile_active": 1,
                "profile_created": "2019-01-20 06:43:42",
                "profile_updated": "2019-01-20 06:43:42"
            }
        ],
        "total": 2
    }
}

4.A.1.6. system-model-update

Updates a row in the database.

Parameters: system-model-update
Name Validation Description Example
schema required Name of the schema profile
[unique field] required The primary ID or a unique field defined in the provided schema {"profile_id": 1}
[fields] required Fields defined in the provided schema {"profile_name": "John Doe"}
PHP Example: system-model-update
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']
        ->setStage('schema', 'profile')
        ->setStage('profile_id', 1)
        ->setStage('profile_name', 'Jane Doe');

    $this->trigger('system-model-update', $payload['request'], $payload['response']);
});
CLI Example: system-model-update
$ bin/cradle system-model-update schema=profile profile_id=1 profile_name="Jane Doe"
Example Response: system-model-update
{
    "error": false,
    "results": {
        "profile_id": 1,
        "profile_name": "Jane Doe",
        "profile_active": 1,
        "profile_created": "2019-01-01 00:00:00"
        "profile_updated": "2019-01-01 00:00:01"
    }
}

4.A.2. System Relational Events

Relational events are used to manage the relations between objects.

Links an object with another object. The provided schemas for both the objects should be already related to each other where schema1 is the base schema and schema2 is the defined relation for example auth_profile table in the database. This would make schema1=auth and schema2=profile

Name Validation Description Example
schema1 required Name of the base schema auth
schema2 required Name of the defined relation profile
[primary key 1] required The primary ID of the base schema {"auth_id": 1}
[primary key 2] required The primary ID of the defined relation {"profile_id": 1} 
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']
        ->setStage('schema1', 'auth')
        ->setStage('schema2', 'profile')
        ->setStage('auth_id', 100)
        ->setStage('profile_id', 100);

    $this->trigger('system-relation-link', $payload['request'], $payload['response']);
});

$ bin/cradle system-relation-link schema1=auth schema2=profile auth_id=100 profile_id=100

{
    "error": false
}

Unlinks an object from another object. The provided schemas for both the objects should be already related to each other where schema1 is the base schema and schema2 is the defined relation for example auth_profile table in the database. This would make schema1=auth and schema2=profile

Name Validation Description Example
schema1 required Name of the base schema auth
schema2 required Name of the defined relation profile
[primary key 1] required The primary ID of the base schema {"auth_id": 1}
[primary key 2] required The primary ID of the defined relation {"profile_id": 1} 
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']
        ->setStage('schema1', 'auth')
        ->setStage('schema2', 'profile')
        ->setStage('auth_id', 100)
        ->setStage('profile_id', 100);

    $this->trigger('system-relation-link', $payload['request'], $payload['response']);
});

$ bin/cradle system-relation-unlink schema1=auth schema2=profile auth_id=100 profile_id=100

{
    "error": false
}

Unlinks all objects from another object. The provided schemas for both the objects should be already related to each other where schema1 is the base schema and schema2 is the defined relation for example auth_profile table in the database. This would make schema1=auth and schema2=profile

Name Validation Description Example
schema1 required Name of the base schema auth
schema2 required Name of the defined relation profile
[primary key 1] required The primary ID of the base schema {"auth_id": 1} 
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']
        ->setStage('schema1', 'auth')
        ->setStage('schema2', 'profile')
        ->setStage('auth_id', 100);

    $this->trigger('system-relation-link', $payload['request'], $payload['response']);
});

$ bin/cradle system-relation-unlink-all schema1=auth schema2=profile auth_id=100

{
    "error": false
}

4.A.3. History Events

History events manages the changes of content in the system

4.A.3.1. history-model-versions

Retrieves the revision changes of a history item

Parameters: history-model-versions
Name Validation Description Example
history_id required The primary history ID 1
PHP Example: history-model-versions
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']->setStage('history_id', 75);

    $this->trigger('history-model-versions', $payload['request'], $payload['response']);
});
CLI Example: history-model-versions
$ bin/cradle history-model-versions history=75
Example Response: history-model-versions
{
    "error": false,
    "results": {
        "history": {
            "history_id": 75,
            "history_activity": "updated Application #1",
            "history_meta": {...},
            "history_page": "/admin/system/model/app/update/1",
            "history_path": "611ad7939e287573aca1f772bfbc643a.json",
            "history_remote_address": "127.0.0.1",
            "history_table_id": 1,
            "history_table_name": "app",
            "history_type": "update",
            "history_flag": 1,
            "history_active": 1,
            "history_created": "2019-01-30 08:10:05",
            "history_updated": "2019-01-30 08:10:05",
            "profile_id": 1,
            "profile_name": "John Doe",
            "profile_active": 1,
            "profile_created": "2019-01-20 06:43:42",
            "profile_updated": "2019-01-20 06:43:42"
        },
        "original": {
            "profile_id": 1,
            "app_id": 1,
            "app_domain": "dev.cradle.local",
            "app_title": "Sample App",
            "app_updated": "2019-01-30 08:10:05"
        },
        "current": {
            "profile_id": 1,
            "app_id": 1,
            "app_domain": "dev.cradle.local",
            "app_title": "Sample App 2",
            "app_updated": "2019-01-30 08:10:05"
        }
    }
}

4.A.4. Authentication Events

Authentication events manages users from sign up to log in.

4.A.4.1. auth-create

Creates a user that can login.

Parameters: auth-create
Name Validation Description Example
profile_name required Name of the user Jane Doe
auth_type optional Name of the role to assume admin
auth_active optional Whether if this already verified 1
auth_slug required Email Address jane@doe.com
auth_password required Password 123
confirm required Confirming the password 123
PHP Example: auth-create
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']
        ->setStage('profile_name', 'Jane Doe')
        ->setStage('auth_type', 'user')
        ->setStage('auth_active', 1)
        ->setStage('auth_slug', 'jane@doe.com')
        ->setStage('auth_password', '123')
        ->setStage('confirm', '123');

    $this->trigger('auth-create', $payload['request'], $payload['response']);
});
CLI Example: auth-create
$ bin/cradle auth-create profile_name="Jane Doe" auth_type=user auth_active=1 auth_slug=jane@doe.com auth_password=123 confirm=123
Example Response: auth-create
{
    "error": false,
    "results": {
        "auth_id": 2,
        "auth_type": 2,
        "auth_slug": "jane@doe.com",
        "auth_active": 1,
        "auth_created": "2019-01-30 08:10:05",
        "auth_updated": "2019-01-30 08:10:05",
        "profile_id": 2,
        "profile_name": "Jane Doe",
        "profile_active": 1,
        "profile_created": "2019-01-30 08:10:05",
        "profile_updated": "2019-01-30 08:10:05"
    }
}

4.A.4.2. auth-detail

Gets the users information, including password

Use this event securely
Parameters: auth-detail
Name Validation Description Example
[unique field] required auth_id or auth_slug {"auth_id": 1}
PHP Example: auth-detail
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']->setStage('auth_slug', 'jane@doe.com');

    $this->trigger('auth-detail', $payload['request'], $payload['response']);
});
CLI Example: auth-detail
$ bin/cradle auth-detail auth_slug=jane@doe.com
Example Response: auth-detail
{
    "error": false,
    "results": {
        "auth_id": 2,
        "auth_type": 2,
        "auth_slug": "jane@doe.com",
        "auth_password": "$32abcd54...",
        "auth_active": 1,
        "auth_created": "2019-01-30 08:10:05",
        "auth_updated": "2019-01-30 08:10:05",
        "profile_id": 2,
        "profile_name": "Jane Doe",
        "profile_active": 1,
        "profile_created": "2019-01-30 08:10:05",
        "profile_updated": "2019-01-30 08:10:05"
    }
}

4.A.4.3. auth-forgot

Sends out an email to recover the account.

Parameters: auth-forgot
Name Validation Description Example
[unique field] required auth_id or auth_slug {"auth_id": 1}
PHP Example: auth-forgot
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']->setStage('auth_slug', 'jane@doe.com');

    $this->trigger('auth-forgot', $payload['request'], $payload['response']);
});
CLI Example: auth-forgot
$ bin/cradle auth-forgot auth_slug=jane@doe.com
Example Response: auth-forgot
{
    "error": false,
    "results": {
        "auth_id": 2,
        "auth_type": 2,
        "auth_slug": "jane@doe.com",
        "auth_active": 1,
        "auth_created": "2019-01-30 08:10:05",
        "auth_updated": "2019-01-30 08:10:05",
        "profile_id": 2,
        "profile_name": "Jane Doe",
        "profile_active": 1,
        "profile_created": "2019-01-30 08:10:05",
        "profile_updated": "2019-01-30 08:10:05"
    }
}

4.A.4.5. auth-update

Updates a user’s information.

Parameters: auth-update
Name Validation Description Example
profile_name optional Name of the user Jane Doe
auth_type optional Name of the role to assume admin
auth_active optional Whether if this already verified 1
auth_slug optional Email Address jane@doe.com
auth_password optional Password 123
confirm optional Confirming the password 123
PHP Example: auth-update
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']
        ->setStage('profile_name', 'Jane Doe')
        ->setStage('auth_type', 'user')
        ->setStage('auth_active', 1)
        ->setStage('auth_slug', 'jane@doe.com')
        ->setStage('auth_password', '123')
        ->setStage('confirm', '123');

    $this->trigger('auth-update', $payload['request'], $payload['response']);
});
CLI Example: auth-update
$ bin/cradle auth-update profile_name="Jane Doe" auth_type=user auth_active=1 auth_slug=jane@doe.com auth_password=123 confirm=123
Example Response: auth-update
{
    "error": false,
    "results": {
        "auth_id": 2,
        "auth_type": 2,
        "auth_slug": "jane@doe.com",
        "auth_active": 1,
        "auth_created": "2019-01-30 08:10:05",
        "auth_updated": "2019-01-30 08:10:05",
        "profile_id": 2,
        "profile_name": "Jane Doe",
        "profile_active": 1,
        "profile_created": "2019-01-30 08:10:05",
        "profile_updated": "2019-01-30 08:10:05"
    }
}

4.A.4.6. auth-login

Checks if the user email and password are correct

Use this event securely
Parameters: auth-login
Name Validation Description Example
auth_slug required Log In Email jane@doe.com
auth_password required Password 123
PHP Example: auth-login
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']
        ->setStage('auth_slug', 'jane@doe.com')
        ->setStage('auth_password', '123');

    $this->trigger('auth-login', $payload['request'], $payload['response']);
});
CLI Example: auth-login
$ bin/cradle auth-login auth_slug=jane@doe.com auth_password=123
Example Response: auth-login
{
    "error": false,
    "results": {
        "auth_id": 2,
        "auth_type": 2,
        "auth_slug": "jane@doe.com",
        "auth_active": 1,
        "auth_created": "2019-01-30 08:10:05",
        "auth_updated": "2019-01-30 08:10:05",
        "profile_id": 2,
        "profile_name": "Jane Doe",
        "profile_active": 1,
        "profile_created": "2019-01-30 08:10:05",
        "profile_updated": "2019-01-30 08:10:05"
    }
}

4.A.4.8. auth-verify

Sends out an email to verify the account

Parameters: auth-verify
Name Validation Description Example
[unique field] required auth_id or auth_slug {"auth_id": 1}
PHP Example: auth-verify
cradle(function() {
    //make a Request and Response
    $payload = $this->makePayload();

    //set the staging data
    $payload['request']->setStage('auth_slug', 'jane@doe.com');

    $this->trigger('auth-verify', $payload['request'], $payload['response']);
});
CLI Example: auth-verify
$ bin/cradle auth-verify auth_slug=jane@doe.com
Example Response: auth-verify
{
    "error": false,
    "results": {
        "auth_id": 2,
        "auth_type": 2,
        "auth_slug": "jane@doe.com",
        "auth_active": 1,
        "auth_created": "2019-01-30 08:10:05",
        "auth_updated": "2019-01-30 08:10:05",
        "profile_id": 2,
        "profile_name": "Jane Doe",
        "profile_active": 1,
        "profile_created": "2019-01-30 08:10:05",
        "profile_updated": "2019-01-30 08:10:05"
    }
}