Containers

There are two relevant traits in the Container mechanics. Your “container” object should implement ContainerTrait and your child objects should implement TrackableTrait (if not, the $owner/$elements links will not be established)

If both parent and child implement AppScopeTrait then the property of AppScopeTrait::$app will be copied from parent to the child also.

If your child implements InitializerTrait then the method InitializerTrait::init will also be invoked after linking is done.

You will be able to use ContainerTrait::getElement() to access elements inside container:

$object->add(new AnotherObject(), 'test');
$anotherObject = $object->getElement('test');

If you additionally use TrackableTrait together with NameTrait then your objects also receive unique “name”. From example above:

$object->name == “app_object_4”
$anotherObject->name == “app_object_4_test”

Name Trait

trait Atk4\Core\NameTrait: Name trait only adds the ‘name’ property. Normally you don’t have to use it because TrackableTrait automatically inherits this trait. Due to issues with PHP5 if both ContainerTrait and TrackableTrait are using NameTrait and then both applied on the object, the clash results in “strict warning”. To avoid this, apply NameTrait on Containers only if you are NOT using TrackableTrait.

Properties

property Atk4\Core\NameTrait::$name: Name of the object.

Methods

None

CollectionTrait

trait Atk4\Core\CollectionTrait

This trait makes it possible for you to add child objects into your object, but unlike “ContainerTrait” you can use multiple collections stored as different array properties.

This class does not offer automatic naming, so if you try to add another element with same name, it will result in exception.

Example:

class Form
{
    use CollectionTrait;

    protected array $fields = [];

    public function addField(string $name, $seed = [])
    {
        $seed = Factory::mergeSeeds($seed, [FieldMock::class]);

        $field = Factory::factory($seed, ['name' => $name]);

        $this->_addIntoCollection($name, $field, 'fields');

        return $field;
    }

    public function hasField(string $name): bool
    {
        return $this->_hasInCollection($name, 'fields');
    }

    public function getField(string $name)
    {
        return $this->_getFromCollection($name, 'fields');
    }

    public function removeField(string $name)
    {
        $this->_removeFromCollection($name, 'fields');
    }
}

Methods

Atk4\Core\CollectionTrait::_addIntoCollection(string $name, object $object, string $collection)

Adds a new element into collection:

public function addField(string $name, $seed = [])
{
    $field = Factory::factory($seed);

    $this->_addIntoCollection($name, $field, 'fields');

    return $field;
}

Factory usage is optional but would allow you to pass seed into addField()

Atk4\Core\CollectionTrait::_removeFromCollection(string $name, string $collection): Remove element with a given name from collection.

Atk4\Core\CollectionTrait::_hasInCollection(string $name, string $collection): Return object if it exits in collection and false otherwise

Atk4\Core\CollectionTrait::_getFromCollection(string $name, string $collection): Same as _hasInCollection but throws exception if element is not found

Atk4\Core\CollectionTrait::_shortenMl(string $ownerName, string $collectionName, string $itemShortName): Implements name shortening

Shortening is identical to ContainerTrait::_shorten.

Your object can this train together with ContainerTrait. As per June 2019 ATK maintainers agreed to gradually refactor ATK Data to use CollectionTrait for fields, relations, actions.

Container Trait

trait Atk4\Core\ContainerTrait

If you want your framework to keep track of relationships between objects by implementing containers, you can use ContainerTrait. Example:

class MyContainer extends OtherClass
{
    use Atk4\Core\ContainerTrait;

    public function add(object $obq, $args = []): object
    {
        $this->_addContainer($obj, is_string($args) ? ['name' => $args] : $args);

        return $obj;
    }
}

class MyItem
{
    use Atk4\Core\TrackableTrait;
    use Atk4\Core\NameTrait;
}

Now the instances of MyItem can be added to instances of MyContainer and can keep track:

$parent = new MyContainer();
$parent->name = 'foo';
$parent->add(new MyItem(), 'child1');
$parent->add(new MyItem());

echo $parent->getElement('child1')->name;
// foo_child1

if ($parent->hasElement('child1')) {
    $parent->removeElement('child1');
}

foreach ($parent as $child) {
    $child->doSomething();
}

Child object names will be derived from the parent name.

Properties

property Atk4\Core\ContainerTrait::$elements: Contains a list of objects that have been “added” into the current container. The key is a “shot_name” of the child. The actual link to the element will be only present if child uses both TrackableTrait and NameTrait traits, otherwise the value of array key will be “true”.

Methods

Atk4\Core\ContainerTrait::add($obj, $args = []): If you are using ContainerTrait only, then you can safely use this add() method. If you are also using factory, or initializer then redefine add() and call _addContainer, _addFactory,.

Atk4\Core\ContainerTrait::_addContainer(object $element, array $args) → void

Add element into container. Normally you should create a method add() inside your class that will execute this method. Because multiple traits will want to contribute to your add() method, you should see sample implementation in ContainerTrait::add.

Your minimum code should be:

public function add(object $obj, $args = []): object
{
    $this->_addContainer($obj, is_string($args) ? ['name' => $args] : $args);

    return $obj;
}

$args be in few forms:

$args = ['child_name'];
$args = 'child_name';
$args = ['child_name', 'db' => $mydb];
$args = ['name' => 'child_name']; // obsolete, backward-compatible

Method throws an exception if child with the same name already exists.

Atk4\Core\ContainerTrait::removeElement($shortName): Will remove element from $elements. You can pass either shortName or the object itself. This will be called if TrackableTrait::destroy is called.

Atk4\Core\ContainerTrait::_shorten(string $ownerName, string $itemShortName)

Given the long owner name and short child name, this method will attempt to shorten the length of your children. The reason for shortening a name is to impose reasonable limits on overly long names. Name can be used as key in the GET argument or form field, so for a longer names they will be shortened.

This method will only be used if current object has AppScopeTrait, since the application is responsible for keeping shortenings.

Atk4\Core\ContainerTrait::getElement($shortName): Given a short-name of the element, will return the object. Throws exception if object with such shortName does not exist.

Atk4\Core\ContainerTrait::hasElement($shortName): Given a short-name of the element, will return true if object with such shortName exists, otherwise false.

Atk4\Core\ContainerTrait::_uniqueElementName(): Internal method to create unique name for an element.

Trackable Trait

trait Atk4\Core\TrackableTrait

Trackable trait implements a few fields for the object that will maintain it’s relationship with the owner (parent).

When name is set for container, then all children will derive their names of the parent.

Parent: foo
Child: foo_child1

The name will be unique within this container.

Properties

property Atk4\Core\TrackableTrait::$owner: Will point to object which has add()ed this object. If multiple objects have added this object, then this will point to the most recent one.

property Atk4\Core\TrackableTrait::$shortName: When you add item into the owner, the “shortName” will contain short name of this item.

Methods

Atk4\Core\TrackableTrait::getDesiredName()

Normally object will try to be named after it’s class, if the name is omitted. You can override this method to implement a different mechanics.

If you pass ‘desired_name’ => ‘heh’ to a constructor, then it will affect the preferred name returned by this method. Unlike ‘name’ => ‘heh’ it won’t fail if another element with this name exists, but will add ‘_2’ postfix.

Atk4\Core\TrackableTrait::destroy(): If object owner is set, then this will remove object from it’s owner elements reducing number of links to the object. Normally PHP’s garbage collector should remove object as soon as number of links is zero.