Skip to content

Commit

Permalink
unify cs
Browse files Browse the repository at this point in the history
  • Loading branch information
@mvorisek
mvorisek committed Aug 18, 2022
1 parent 241465c commit 2d822f5
Show file tree
Hide file tree
Showing 22 changed files with 160 additions and 134 deletions.
17 changes: 11 additions & 6 deletions docs/container.rst
View file
Expand Up @@ -105,8 +105,10 @@ Methods
Adds a new element into collection::

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

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

Expand Down Expand Up @@ -145,15 +147,18 @@ Container Trait
by implementing containers, you can use :php:trait:`ContainerTrait`.
Example::

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

function add($obq, $args = []) {
public function add($obq, $args = [])
{
return $this->_addContainer($obj, $args);
}
}

class MyItem {
class MyItem
{
use Atk4\Core\TrackableTrait;
use Atk4\Core\NameTrait;
}
Expand Down Expand Up @@ -207,7 +212,7 @@ Methods

Your minimum code should be::

function add($obj, $args = [])
public function add($obj, $args = [])
{
return $this->_addContainer($obj, $args);
}
Expand All @@ -217,7 +222,7 @@ Methods
$args = ['child_name'];
$args = 'child_name';
$args = ['child_name', 'db' => $mydb];
$args = ['name' => 'child_name']; // obsolete, backward-compatible
$args = ['name' => 'child_name']; // obsolete, backward-compatible

Method will return the object. Will throw exception if child with same
name already exist.
Expand Down
6 changes: 3 additions & 3 deletions docs/debug.rst
View file
Expand Up @@ -46,9 +46,9 @@ Various objects may implement DebugTrait and also invoke $this->debug(), but in
most cases this will simply be ignored right away unless you manually enable
debugging for the object::

$obj1->debug(); // enable debugging
$obj1->debug(false); // disable debugging
$obj1->debug(true); // also enables debugging
$obj1->debug(); // enable debugging
$obj1->debug(false); // disable debugging
$obj1->debug(true); // also enables debugging

$obj1->debug('test1'); // will go to logger
$obj2->debug('test2'); // will not go to logger because debug is not enabled for this object
Expand Down
17 changes: 11 additions & 6 deletions docs/di.rst
View file
Expand Up @@ -14,7 +14,7 @@ dependencies on another object/class. For instance::

$book = new Book();
$book->name = 'foo';
$book->save(); // saves somewhere??
$book->save(); // saves somewhere??

The above code uses some ORM notation and the book record is saved into the
database. But how does Book object know about the database? Some frameworks
Expand Down Expand Up @@ -70,10 +70,12 @@ How to use DiContainerTrait
Calling this method will set object's properties. If any specified property
is undefined then it will be skipped. Here is how you should use trait::

class MyObj {
class MyObj
{
use DiContainerTrait;

function __construct($defaults = []) {
public function __construct($defaults = [])
{
$this->setDefaults($defaults, true);
}
}
Expand All @@ -86,16 +88,19 @@ like this::

This is done by overriding setMissingProperty method::

class MyObj {
class MyObj
{
use DiContainerTrait {
setMissingProperty as private _setMissingProperty;
}

function __construct($defaults = []) {
public function __construct($defaults = [])
{
$this->setDefaults($defaults, true);
}

function setMissingProperty($key, $value) {
protected function setMissingProperty($key, $value)
{
// do something with $key / $value

// will either cause exception or will ignorance
Expand Down
11 changes: 7 additions & 4 deletions docs/dynamicmethod.rst
View file
Expand Up @@ -10,7 +10,9 @@ Introduction
Adds ability to add methods into objects dynamically. That's like a "trait"
feature of a PHP, but implemented in run-time::

$object->addMethod('test', function ($o, $args) { echo 'hello, ' . $args[0]; });
$object->addMethod('test', function ($o, $args) {
echo 'hello, ' . $args[0];
});
$object->test('world');

Global Methods
Expand Down Expand Up @@ -38,9 +40,10 @@ When calling dynamic method first argument which is passed to the method will
be object itself. Dynamic method will also receive all arguments which are
given when you call this dynamic method::

$m->addMethod('sum', function ($m, $a, $b) { return $a + $b; });
echo $m->sum(3, 5);
// 8
$m->addMethod('sum', function ($m, $a, $b) {
return $a + $b;
});
echo $m->sum(3, 5); // 8

Properties
==========
Expand Down
3 changes: 2 additions & 1 deletion docs/exception.rst
View file
Expand Up @@ -34,7 +34,8 @@ The other option is to supply error is:
try {
$field->validate();
} catch (Validation_Exception $e) {
$e->addMoreInfo('field', $field);
$e->addMoreInfo('field', $field

throw $e;
}

Expand Down
61 changes: 32 additions & 29 deletions docs/factory.rst
View file
Expand Up @@ -16,14 +16,14 @@ things like:

Thanks to Factory trait, the following code::

$button = $app->add(['Button', 'A Label', 'icon' => 'book', 'action' => My\Action::class]);
$button = $app->add(['Button', 'A Label', 'icon' => 'book', 'action' => My\Action::class]);

can replace this::

$button = new \Atk4\Ui\Button('A Label');
$button->icon = new \Atk4\Ui\Icon('book');
$button->action = new My\Action();
$app->add($button);
$button = new \Atk4\Ui\Button('A Label');
$button->icon = new \Atk4\Ui\Icon('book');
$button->action = new My\Action();
$app->add($button);

Type Hinting
------------
Expand All @@ -48,11 +48,11 @@ Seed
Using "class" as opposed to initialized object yields many performance gains,
as initialization of the class may be delayed until it's required. For instance::

$model->hasMany('Invoices', Invoice::class);
$model->hasMany('Invoices', Invoice::class);

// is faster than
// is faster than

$model->hasMany('Invoices', new Invoice());
$model->hasMany('Invoices', new Invoice());

That is due to the fact that creating instance of "Invoice" class is not required
until you actually traverse into it using `$model->ref('Invoices')` and can offer
Expand All @@ -61,14 +61,14 @@ into the object.

Suppose you want to add a button with an icon::

$button = $view->add('Button');
$button->icon = new Icon('book');
$button = $view->add('Button');
$button->icon = new Icon('book');

It's possible that some call-back execution will come before button rendering, so
it's better to replace icon with the class::

$button = $view->add('Button');
$button->icon = Icon::class;
$button = $view->add('Button');
$button->icon = Icon::class;

In this case, however - it is no longer possible to pass the "book" parameter to
the constructor of the Icon class.
Expand All @@ -77,31 +77,31 @@ This problem is solved in ATK with "Seeds".

A Seed is an array consisting of class name/object, named and numeric arguments::

$seed = [Button::class, 'My Label', 'icon' => 'book'];
$seed = [Button::class, 'My Label', 'icon' => 'book'];

Seed with and without class
---------------------------

There are two types of seeds - with class name and without. The one above contains
the class and is used when user needs a flexibility to specify a class::

$app->add(['Button', 'My Label', 'icon' => 'book']);
$app->add(['Button', 'My Label', 'icon' => 'book']);

The other seed type is class-less and can be used in situations where there are no
ambiguity about which class is used::

$button->icon = ['book'];
$button->icon = ['book'];

Either of those seeds can be replaced with the Object::

$button = $app->add(new Button('My Label'));
$button->icon = new Icon('book');
$button = $app->add(new Button('My Label'));
$button->icon = new Icon('book');

If seed is a string then it would be treated as class name. For a class-less seed
it would be treaded as a first argument to the construcor::

$button = $app->add('Button');
$button->icon = 'book';
$button = $app->add('Button');
$button->icon = 'book';

Lifecycle of argument-bound seed
--------------------------------
Expand Down Expand Up @@ -157,23 +157,23 @@ e.g. ``Action`` may have to be configured individually.
Agile Core implements a mechanism to make that possible through using Factory::factory()
method and specifying a seed argument::

use Atk4\Ui\Button;
use Atk4\Ui\Button;

$button = Factory::factory([Button::Class, 'A Label', 'icon' => ['book'], 'action' => new Action(..)]);
$button = Factory::factory([Button::Class, 'A Label', 'icon' => ['book'], 'action' => new Action(..)]);

Note that passing 'icon' => ['book'] will also use factory to initialize icon object.

Finally, if you are using IDE and type hinting, a preferred code would be::

use Atk4\Ui\Button;
Factory::factory($button = new Button('A Label'), ['icon' => ['book'], 'action' => new Action(..)]);
use Atk4\Ui\Button;
Factory::factory($button = new Button('A Label'), ['icon' => ['book'], 'action' => new Action(..)]);

This will properly set type to $button variable, while still setting properties for icon/action. More
commonly, however, you would use this through the add() method::

use Atk4\Ui\Button;
use Atk4\Ui\Button;

$view->add([$button = new Button('A Label'), 'icon' => ['book'], 'action' => new Action('..')]);
$view->add([$button = new Button('A Label'), 'icon' => ['book'], 'action' => new Action('..')]);

Seed Components
---------------
Expand Down Expand Up @@ -202,7 +202,7 @@ Class-less seeds
You cannot create object from a class-less seed, simply because factory would not know which class
to use. However it can be passed as a second argument to the factory::

$this->icon = Factory::factory([Icon::class, 'book'], $this->icon);
$this->icon = Factory::factory([Icon::class, 'book'], $this->icon);

This will use class icon and first argument 'book' as default, but would use exitsing seed version if
it was specified. Also it will preserve the object value of an icon.
Expand Down Expand Up @@ -257,10 +257,12 @@ precedence:
The next example will help you understand the precedence of different argument
values. See my description below the example::

class RedButton extends Button {
class RedButton extends Button
{
protected $icon = 'book';

protected function init(): void {
protected function init(): void
{
parent::init();

$this->icon = 'right arrow';
Expand Down Expand Up @@ -418,7 +420,8 @@ Model::addField, Form::addButton, FormLayout::addHeader imply that the class of
an added object is known so the argument you specify to those methods ends up
being a factory's $default::

function addButton($label) {
public function addButton($label)
{
return $this->add(
Factory::factory([Button::class, null, 'secondary'], $label);
'Buttons'
Expand Down
30 changes: 17 additions & 13 deletions docs/hook.rst
View file
Expand Up @@ -30,7 +30,9 @@ The framework or application would typically execute hooks like this::

You can register multiple call-backs to be executed for the requested `spot`::

$obj->onHook('spot', function ($obj) { echo "Hook 'spot' is called!"; });
$obj->onHook('spot', function ($obj) {
echo "Hook 'spot' is called!";
});

Adding callbacks
================
Expand All @@ -57,7 +59,7 @@ In this case a method with same name as $spot will be used as callback::
});
}

function beforeUpdate()
protected function beforeUpdate()
{
// will be called from the hook
}
Expand All @@ -73,20 +75,20 @@ hook with priority 1 it will always be executed before any hooks with priority
Normally hooks are executed in the same order as they are added, however if you
use negative priority, then hooks will be executed in reverse order::

$obj->onHook('spot', third, [], -1);
$obj->onHook('spot', third, [], -1);

$obj->onHook('spot', second, [], -5);
$obj->onHook('spot', first, [], -5);
$obj->onHook('spot', second, [], -5);
$obj->onHook('spot', first, [], -5);

$obj->onHook('spot', fourth, [], 0);
$obj->onHook('spot', fifth, [], 0);
$obj->onHook('spot', fourth, [], 0);
$obj->onHook('spot', fifth, [], 0);

$obj->onHook('spot', ten, [], 1000);
$obj->onHook('spot', ten, [], 1000);

$obj->onHook('spot', sixth, [], 2);
$obj->onHook('spot', seventh, [], 5);
$obj->onHook('spot', sixth, [], 2);
$obj->onHook('spot', seventh, [], 5);
$obj->onHook('spot', eight);
$obj->onHook('spot', nine, [], 5);
$obj->onHook('spot', nine, [], 5);


.. php:method:: hook($spot, $args = null)
Expand Down Expand Up @@ -177,12 +179,14 @@ Using references in hooks
In some cases you want hook to change certain value. For example when model
value is set it may call normalization hook (methods will change $value)::

function set($field, $value) {
public function set($field, $value) {
$this->hook('normalize', [&$value]);
$this->data[$field] = $value;
}

$m->onHook('normalize', function (&$a) { $a = trim($a); });
$m->onHook('normalize', function (&$a) {
$a = trim($a);
});

Checking if hook has callbacks
==============================
Expand Down

0 comments on commit 2d822f5

Please sign in to comment.