Releasing 2.0.2 into master (#150)

* Clean up badges in README file (#116)

* improve badges

* cleanup

* wip

* wip

* wip

* Configuration Elements cannot be replaced (#117)

* Apply fixes from StyleCI

* Update composer.json

* Update release-drafter.yml

* Update release-drafter.yml

* Create bundler.yml

* Add POC for "CRUD::addTo($app)" syntax (#123)

* Add POC for "CRUD::addTo($app)" syntax

* Apply fixes from StyleCI

* Add unit tests

* Apply fixes from StyleCI

* remove this weird file

* [REFACTOR] rename addHook to onHook with argument naming consistency (#124)

* rename addHook to onHook with argument naming consistency

* Apply fixes from StyleCI

* rename addHook to onHook with argument naming consistency

* update docs

* hook $this by default (#126)

* assign $this as default value for fx

* update exception info

* update docs

* Move doc builder instructions into Docker (#125)

* Releasing 2.0.1 into master (#122)

* Clean up badges in README file (#116)

* improve badges

* cleanup

* wip

* wip

* wip

* Configuration Elements cannot be replaced (#117)

* Apply fixes from StyleCI

* Update composer.json

* Update release-drafter.yml

* Update release-drafter.yml

* Create bundler.yml

* Setting release dependencies

Co-authored-by: Romans Malinovskis <me@nearly.guru>
Co-authored-by: Georg Marx <bepixeld@users.noreply.github.com>
Co-authored-by: Imants Horsts <DarkSide666@users.noreply.github.com>
Co-authored-by: GitHub Web Flow <noreply@github.com>

* Add POC for "CRUD::addTo($app)" syntax

* Apply fixes from StyleCI

* Add unit tests

* Apply fixes from StyleCI

* remove this weird file

* Add dockerfile for easier doc preview

* Update instructions

* add doc integration instructions for PhpStorm

* Add mention of addTo() into the docs

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Georg Marx <bepixeld@users.noreply.github.com>
Co-authored-by: Imants Horsts <DarkSide666@users.noreply.github.com>
Co-authored-by: GitHub Web Flow <noreply@github.com>

* Rename hook spot argument (#127)

* improve hook arguments versatility

* rename $hookSpot to $spot

* update tests

* update comment

* Apply fixes from StyleCI

* improve hook default argument versatility

* Apply fixes from StyleCI

* Update unit-tests.yml

* Update unit-tests.yml

* Update unit-tests.yml

* avoid code duplication (#128)

* avoid code duplication

* outline logic by using brackets

* setLayout -> initLayout (#130)

* setLayout -> initLayout

* Apply fixes from StyleCI

* style

* Rename HEAD to develop for Composer in unit tests (#135)

* Fix EOL to NL (#132)

* Do not fail-fast PHP test matrix (#136)

* Improve StaticAddToTrait trait (#139)

* Fix initial StaticAddTo trait

* Prevent bad addTo usage

* Improve addTo method

* Fix add_arguments in tests

* Add similar method to addTo for seeds with class name

* Improve readability and prevent even more bad usage

* Fix typo

* Improve StaticAddTo tests and add unsafe method for BC UI impl. (#140)

* Improve StaticAddTo tests

* Add unsafe method of addToWithClassName to skip instanceof check

* Do not wrap exception message in array (#141)

* Add skip_add param to StaticAddToTrait trait methods (#143)

* Require class name in seed for addToWithClassName methods (#144)

* Update release-drafter.yml

* Update release-drafter.yml

* Update StaticAddToTrait.php

* Improve hooks and allow to delete/check specific priority (#133)

* Improve hooks and allow to delete/check specific priority

* Fix tests

* Introduce indexes hooks

* Fix hook doc

* fix compatibility

* Fix bad phpdoc

* Add injection of solutions in Exception constructor (#119)

* Rapid add solutions in constructor

* Apply fixes from StyleCI

* fixes

* Apply fixes from StyleCI

* style fix

Co-authored-by: DarkSide <imants.horsts@inbox.lv>
Co-authored-by: Imants Horsts <DarkSide666@users.noreply.github.com>

* Fix CS - do not import classes without namespace (#147)

* Fix CS - do not import classes without namespace

* Apply fixes from StyleCI

Co-authored-by: Romans Malinovskis <me@nearly.guru>

* Align exception header properly (#148)

* Setting release dependencies

Co-authored-by: Romans Malinovskis <me@nearly.guru>
Co-authored-by: Georg Marx <bepixeld@users.noreply.github.com>
Co-authored-by: Imants Horsts <imants.horsts@inbox.lv>
Co-authored-by: Imants Horsts <DarkSide666@users.noreply.github.com>
Co-authored-by: Georgi Hristov <georgehristov@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: GitHub Web Flow <noreply@github.com>
Co-authored-by: Michael Voříšek <mvorisek@mvorisek.cz>
Co-authored-by: Francesco Danti <fdanti@gmail.com>

.github/workflows/release-drafter.yml

@@ -11,6 +11,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # Drafts your next Release notes as Pull Requests are merged into "master"
-      - uses: toolmantim/release-drafter@master
+      - uses: toolmantim/release-drafter@v5.6.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/unit-tests.yml

@@ -15,13 +15,17 @@ jobs:
     container:
       image: atk4/image:${{ matrix.php }} # https://github.com/atk4/image
     strategy:
+      fail-fast: false
       matrix:
         php: ['7.2', '7.3', 'latest']
     steps:
-      - uses: actions/checkout@v1
-      # need this to trick composer
+      - uses: actions/checkout@v2
       - run: php --version
-      - run: "git branch develop; git checkout develop"
+
+      # need this to trick composer that this is a "atk4/core:develop" dependency to install atk4/data
+      - name: Rename HEAD to develop for Composer
+        run: git switch -C develop HEAD
+
       - name: Get Composer Cache Directory
         id: composer-cache
         run: |

docs/Dockerfile

@@ -0,0 +1,17 @@
+FROM  python:2-stretch as builder
+
+WORKDIR /www
+
+ADD requirements.txt .
+
+RUN pip install  pip==9.0.1 wheel==0.29.0 \
+    && pip install -r requirements.txt
+
+ADD . .
+
+RUN make html
+#RUN cp -R images build/html/images
+
+FROM  nginx:latest
+
+COPY --from=builder /www/build/html /usr/share/nginx/html

docs/README.md

@@ -1,19 +1,9 @@
-How to build this documentation
+Our documentation can now be built in the Docker.
 
 ```
-sudo apt-get install python-sphinx python-setuptools
-sudo easy_install pip
-
-sudo pip install sphinx_rtd_theme
-sudo pip install sphinxcontrib-phpdomain
-
-make html
+docker build -t docs .
+docker run -p 8080:80 docs
 ```
 
-next open `html/index.html` in your browser
-
-```
-open html/index.html
-```
-
+Open http://localhost:8080/ in your browser.
 

docs/docs.rst

@@ -0,0 +1,43 @@
+================
+Writing ATK Docs
+================
+
+New users of Agile Toolkit rely on documentation. To make it easier for the
+maintainers to update documentation - each component of ATK framework comes
+with a nice documentation builder.
+
+Writing ATK Documentation
+=========================
+
+Open file "docs/index.rst" in your editor. Most editors will support
+"reSTructured Text" through add-on. The support is not perfect, but it works.
+
+If you are updating a feature - find a corresponding ".rst" file. Your editor
+may be able to show you a preview. Modify or extend documentation as needed.
+
+See also: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+
+Building and Testing Documentation
+==================================
+
+Make sure you have "Docker" installed, follow simple instructions in
+"docs/README.md".
+
+Integrating PhpStorm
+--------------------
+
+You can integrate PhpStorm build process like this:
+
+.. figure:: images/doc-build-phpstorm1.png
+   :scale: 50 %
+   :alt: Create build configuration for the Dockerfile
+
+
+.. figure:: images/doc-build-phpstorm2.png
+   :scale: 50 %
+   :alt: Adjust Port settings to expose 80 as 8080
+
+.. figure:: images/doc-build-phpstorm3.png
+   :scale: 50 %
+   :alt: Use "Ctrl+R" anytime to build docs
+

docs/factory.rst

@@ -16,21 +16,33 @@ things like:
 
 Thanks to Factory trait, the following code::
 
-   $view->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);
 
+Type Hinting
+------------
+
+Agile Toolkit 2.1 introduces support for a new syntax. It is functionally
+identical to a short-hand code, but your IDE will properly set type for
+a `$button` to be `class Button` instead of `class View`::
+
+    $button = Button::addTo($view, ['A Label', 'icon'=>'book', 'action'=>My\Action::class]);
+
+The traditional `$view->add` will remain available, there are no plans to
+remove that syntax.
 
 Class Name Resolution
 =====================
 
 Ability to specify only name of the class in ATK is used to keep code clean::
 
-   $app->setLayout('Centered');
+   $app->initLayout('Centered');
    $form = $app->add('Form');
    $form->addField('food_selection', ['Lookup', 'model'=>Model\Food::class]);
 
@@ -40,7 +52,7 @@ various methods are able to accept short identifiers for a simple syntax.
 
 .. php:method:: normalizeClassName($name, $prefix = null)
 
-So App::setLayout() would call `normalizeClassName($layout, 'atk4\ui\Layout')`,
+So App::initLayout() would call `normalizeClassName($layout, 'atk4\ui\Layout')`,
 and View::add() would call `normalizeClassName($view, 'atk4\ui')` and finally
 Form::addField() would call `normalizeClassName($field, 'atk4\ui\FormField` to
 produce the actual name of the class.
@@ -49,11 +61,11 @@ ATK also fully supports the following two alternative forms::
 
    use MyOwn\Layout;
 
-   $app->setLayout(Layout::class);
+   $app->initLayout(Layout::class);
 
 and::
 
-   $app->setLayout(new MyOwn\Layout());
+   $app->initLayout(new MyOwn\Layout());
    
 In the first case `Layout::class` resolves into string `"MyOwn\Layout"` by the
 PHP and normalizeClassName would leave it alone. In the former case, object is
@@ -69,31 +81,31 @@ classes defined in global namespace::
    class TestLayout {
    }
 
-   $app->setLayout(TestLayout::class);
-   // same as $app->setLayout('TestLayout');
+   $app->initLayout(TestLayout::class);
+   // same as $app->initLayout('TestLayout');
 
 In this case, the call to normalizeClassName would proceed to prefix 'TestLayout' layout
 into `\atk4\ui\Layout\Test`.
 
-The solution in this case is to use `$app->setLayout('\TestLayout')`
+The solution in this case is to use `$app->initLayout('\TestLayout')`
 
 Name Resoluion Safety
 ---------------------
 
 While you specify name of the layout yourself, it is not a problem, but if
 you have a code like this::
 
-   $app->setLayout($_GET['layout']);
+   $app->initLayout($_GET['layout']);
 
 Although it seems harmless, technically argument can point to ANY class, which
 will be loaded and code in this class executed. This can be solved by using
 a '.' prefix in front of the relative class name::
 
-   $app->setLayout('.'.$_GET['layout']);
+   $app->initLayout('.'.$_GET['layout']);
 
    // or 
 
-   $app->setLayout('.Centered');
+   $app->initLayout('.Centered');
 
 Sub-namespaces
 --------------
@@ -103,12 +115,12 @@ Sometimes developers prefer to use sub-namespaces, so instead of
 to use `\atk4\ui\Layout\Centererd\Login`. This becomes another problem
 for the resolution::
 
-   $app->setLayout('Centered\Login');
+   $app->initLayout('Centered\Login');
 
 This actually looks like the a string generated by `use Centered; Login::class`
 and to avoid, the following syntax can be used::
 
-   $app->setLayout('Centered/Login');
+   $app->initLayout('Centered/Login');
 
 Substituting / Overriding classes
 ---------------------------------

docs/hook.rst

@@ -30,26 +30,28 @@ The framework or application would typically execute hooks like this::
 
 You can register multiple call-backs to be executed for the requested `spot`::
 
-    $obj->addHook('spot', function($obj){ echo "Hook 'spot' is called!"; });
+    $obj->onHook('spot', function($obj){ echo "Hook 'spot' is called!"; });
 
 Adding callbacks
 ================
 
-.. php:method:: addHook($spot, $callback, $args = null, $priority = 5)
+.. php:method:: onHook($spot, $fx = null, array $args = [], int $priority = 5)
 
 Register a call-back method. Calling several times will register multiple
 callbacks which will be execute in the order that they were added.
 
 Short way to describe callback method
 =====================================
 
-There is a concise syntax for using $callback by specifying object only.
+There is a concise syntax for using $fx by specifying object only.
+In case $fx is omitted then $this object is used as $fx.
+
 In this case a method with same name as $spot will be used as callback::
 
     function init() {
         parent::init();
 
-        $this->addHook('beforeUpdate', $this);
+        $this->onHook('beforeUpdate');
     }
 
     function beforeUpdate($obj){
@@ -67,20 +69,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->addHook('spot', third,    null, -1);
+    $obj->onHook('spot', third,    [], -1);
 
-    $obj->addHook('spot', second,   null, -5);
-    $obj->addHook('spot', first,    null, -5);
+    $obj->onHook('spot', second,   [], -5);
+    $obj->onHook('spot', first,    [], -5);
 
-    $obj->addHook('spot', fourth,   null, 0);
-    $obj->addHook('spot', fifth,    null, 0);
+    $obj->onHook('spot', fourth,   [], 0);
+    $obj->onHook('spot', fifth,    [], 0);
 
-    $obj->addHook('spot', ten,      null, 1000);
+    $obj->onHook('spot', ten,      [], 1000);
 
-    $obj->addHook('spot', sixth,    null, 2);
-    $obj->addHook('spot', seventh,  null, 5);
-    $obj->addHook('spot', eight);
-    $obj->addHook('spot', nine,     null, 5);
+    $obj->onHook('spot', sixth,    [], 2);
+    $obj->onHook('spot', seventh,  [], 5);
+    $obj->onHook('spot', eight);
+    $obj->onHook('spot', nine,     [], 5);
 
 
 .. php:method:: hook($spot, $args = null)
@@ -96,8 +98,8 @@ will be placed in array and returned by hook()::
         return $a+$b;
     };
 
-    $obj->addHook('test', $mul);
-    $obj->addHook('test', $add);
+    $obj->onHook('test', $mul);
+    $obj->onHook('test', $add);
 
     $res1 = $obj->hook('test', [2, 2]);
     // res1 = [4, 4]
@@ -112,7 +114,7 @@ As you see in the code above, we were able to pass some arguments into those
 hooks. There are actually 3 sources that are considered for the arguments:
 
  - first argument to callbacks is always the $object
- - arguments passed as 3rd argument to addHook() are included
+ - arguments passed as 3rd argument to onHook() are included
  - arguments passed as 2nd argument to hook() are included
 
 You can also use key declarations if you wish to override arguments::
@@ -123,8 +125,8 @@ You can also use key declarations if you wish to override arguments::
         return pow($a, $power)+$pow($b, $power);
     }
 
-    $obj->addHook('test', $pow, [2]);
-    $obj->addHook('test', $pow, [7]);
+    $obj->onHook('test', $pow, [2]);
+    $obj->onHook('test', $pow, [7]);
 
     // execute all 3 hooks
     $res3 = $obj->hook('test', [2, 2]);
@@ -151,13 +153,13 @@ Remember that adding breaking hook with a lower priority can prevent other
 call-backs from being executed::
 
 
-    $obj->addHook('test', function($obj){
+    $obj->onHook('test', function($obj){
         $obj->breakHook("break1");
     });
 
-    $obj->addHook('test', function($obj){
+    $obj->onHook('test', function($obj){
         $obj->breakHook("break2");
-    }, null, -5);
+    }, [], -5);
 
     $res3 = $obj->hook('test', [4, 4]);
     // res3 = "break2"
@@ -176,7 +178,7 @@ value is set it may call normalization hook (methods will change $value)::
         $this->data[$field] = $value;
     }
 
-    $m->addHook('normalize', function(&$a) { $a = trim($a); });
+    $m->onHook('normalize', function(&$a) { $a = trim($a); });
 
 Checking if hook has callbacks
 ==============================

docs/index.rst

@@ -20,7 +20,7 @@ Object Containers
 .. figure:: images/containers.png
    :scale: 50 %
 
-Within your application / framework you can quite often have requirement for
+Within your application or framework you can quite often have requirement for
 using containers:
 
  - Form containing fields
@@ -134,8 +134,8 @@ and triggering callbacks::
 
     $object = new AnyClass();
 
-    $object->addHook('test', function($o){ echo 'hello'; }
-    $object->addHook('test', function($o){ echo 'world'; }
+    $object->onHook('test', function($o){ echo 'hello'; }
+    $object->onHook('test', function($o){ echo 'world'; }
 
     $object->hook('test');
     // outputs: helloworld
@@ -273,3 +273,4 @@ Others
 
     debug
     session
+    docs

docs/requirements.txt

@@ -1 +1,2 @@
 sphinxcontrib-phpdomain
+sphinx_rtd_theme

examples/test2.php

@@ -17,7 +17,7 @@ public function doWork()
 }
 
 $c = new MyClass();
-$c->addHook('afterWork', function () {
+$c->onHook('afterWork', function () {
     echo "HOOKed on work\n";
 });
 $c->doWork();