Merge branch 'release/1.1.0'

.travis.yml

@@ -1,12 +1,14 @@
 language: php
 
-sudo: required
-
 php:
     - '5.5'
     - '5.6'
     - '7.0'
 
+cache:
+  directories:
+    - $HOME/.composer/cache
+
 #services:
 #    - mysql
 

CHANGELOG.md

@@ -1,3 +1,12 @@
+## 1.1.0
+
+If any of your objects use ContainerTrait without TrackableTrait, you may need to update
+your code to avoid warnings.
+
+* Significant updates to documentation
+* ContainerTrait no longer add 'name' property. [Use it with TrackableTrait or NameTrait](http://agile-core.readthedocs.io/en/develop/container.html?highlight=nametrait#name-trait)
+* Coding style improved
+
 ## 1.0.3
 
 * Minor cleanups, exception will now show previous exception

README.md

@@ -3,7 +3,7 @@
 **Agile Core is a collection of PHP Traits for designing object-oriented frameworks**
 
 [![Gitter](https://img.shields.io/gitter/room/atk4/data.svg?maxAge=2592000)](https://gitter.im/atk4/dataset?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![Documentation Status](https://readthedocs.org/projects/agile-core/badge/?version=latest)](http://agile-core.readthedocs.io/en/latest/?badge=latest)
+[![Documentation Status](https://readthedocs.org/projects/agile-core/badge/?version=develop)](http://agile-core.readthedocs.io/en/develop/?badge=develop)
 [![License](https://poser.pugx.org/atk4/core/license)](https://packagist.org/packages/atk4/core)
 [![GitHub release](https://img.shields.io/github/release/atk4/core.svg?maxAge=2592000)](https://packagist.org/packages/atk4/core)
 [![Build Status](https://travis-ci.org/atk4/core.png?branch=develop)](https://travis-ci.org/atk4/core)

docs/appscope.rst

@@ -0,0 +1,47 @@
+==============
+AppScope Trait
+==============
+
+.. php:trait:: AppScopeTrait
+
+Introduction
+============
+
+Typical software design will create the application scope. Most frameworks
+relies on "static" properties, methods and classes. This does puts some
+limitations on your implementation (you can't have multiple applications).
+
+App Scope will pass the 'app' property into all the object that you're
+adding, so that you know for sure which application you work with::
+
+Properties
+==========
+
+.. php:attr:: app
+
+    Always points to current Application object
+
+.. php:attr:: max_name_length
+
+    When using mechanism for ContainerTrait, they inherit name of the
+    parent to generate unique name for a child. In a framework it makes
+    sense if you have a unique identifiers for all the objects because
+    this enables you to use them as session keys, get arguments, etc.
+
+    Unfortunatelly if those keys become too long it may be a problem,
+    so ContainerTrait contains a mechanism for auto-shortening the
+    name based around max_name_length. The mechanism does only work
+    if AppScopeTrait is used, $app property is set and has a
+    max_name_length defined.
+    Minimum value is 20.
+
+.. php:attr:: unique_hashes
+
+    As more names are shortened, the substituted part is being placed into
+    this hash and the value contains the new key. This helps to avoid creating
+    many sequential prefixes for the same character sequenece.
+
+Methods
+=======
+
+    None

docs/container.rst

@@ -2,21 +2,63 @@
 Run-Time Tree (Containers)
 ==========================
 
-There are three relevant traits in the Container mechanics. Your "container"
+There are two relevant traits in the Container mechanics. Your "container"
 object should implement :php:trait:`ContainerTrait` and your child objects
 should implement :php:trait:`TrackableTrait` (if not, the $owner/$elements
 links will not be established)
 
-If both parent and child implement :php:trait:`AppScope` then the property
-of :php:attr:`AppScope::app` will be copied from parent to the child also.
+If both parent and child implement :php:trait:`AppScopeTrait` then the property
+of :php:attr:`AppScopeTrait::app` will be copied from parent to the child also.
 
-If your child implements :php:trait:`InitializerTrait` then the method will
-also be invoked after linking is done.
+If your child implements :php:trait:`InitializerTrait` then the method
+:php:meth:`InitializerTrait::init` will also be invoked after linking is done.
+
+You will be able to use :php:meth:`ContainerTrait::getElement()` to access
+elements inside container::
+
+    $object->add(new AnoterObject(), 'test');
+    $another_object = $object->getElement('test');
+
+If you additionally use :php:trait:`TrackableTrait` then your objects
+also receive unique "name". From example above:
+
+* $object->name == "app_object_4"
+* $another_object->name == "app_object_4_test"
+
+
+
+Name Trait
+============
+
+.. php:trait:: ObjectTrait
+
+    Name trait only adds the 'name' property. Normally you don't have to use it
+    because :php:trait:`TrackableTrait` automatically inherits this trait. Due to
+    issues with PHP5 if both Container and Trackable are using NameTrait and then
+    both applied on the object, the clash results in "strict warning". To avoid this,
+    only apply 'NameTrait' on Containers if you are NOT using 'TrackableTrait'.
+
+Properties
+----------
+
+.. php:attr:: name
+
+    Name of the object.
+
+Methods
+-------
+
+    None
+
+
+
+Container Trait
+===============
 
 .. php:trait:: ContainerTrait
 
-When you want your framework to look after relationships between objects by
-implementing containers, you can use :php:trait:`ContainerTrait`. Example::
+    If you want your framework to keep track of relationships between objects by
+    implementing containers, you can use :php:trait:`ContainerTrait`. Example::
 
     class MyContainer extends OtherClass {
         use atk4\core\ContainerTrait;
@@ -30,7 +72,7 @@ implementing containers, you can use :php:trait:`ContainerTrait`. Example::
         use atk4\core\TrackableTrait;
     }
 
-Now the instances of MyClass can be added to one another and can keep track::
+    Now the instances of MyItem can be added to instances of MyContainer and can keep track::
 
     $parent = new MyContainer();
     $parent->name = 'foo';
@@ -47,9 +89,11 @@ Now the instances of MyClass can be added to one another and can keep track::
     $parent->each(function($child) {
         $child->doSomething();
     });
-.. php:attr:: name
 
-    Name of the container. Child names will be derived from the parent.
+Child object names will be derived from the parent name.
+
+Properties
+----------
 
 .. php:attr:: elements
 
@@ -58,6 +102,15 @@ Now the instances of MyClass can be added to one another and can keep track::
     the element will be only present if child uses trait "TrackableTrait",
     otherwise the value of array key will be "true".
 
+Methods
+-------
+
+.. php:meth:: 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 _add_Container, _add_Factory,.
+
 .. php:meth:: _addContainer($element, $args)
 
     Add element into container. Normally you should create a method
@@ -108,54 +161,43 @@ Now the instances of MyClass can be added to one another and can keep track::
     Given a short-name of the element, will return the object. If object with
     such short_name does not exist, will return false instead.
 
-
-
-Internal Methods
-================
-
 .. php:meth:: _unique_element
 
     Internal method to create unique name for an element.
 
 
 
-You will be able to use :php:meth:`ContainerTrait::getElement()` to access
-elements inside container::
-
-    $object->add(new AnoterObject(), 'test');
-    $another_object = $object->getElement('test');
+Trackable Trait
+===============
 
-If you additionally use :php:trait:`TrackableTrait` then your objects
-also receive unique "name". From example above:
+.. php:trait:: TrackableTrait
 
-* $object->name == "app_object_4"
-* $another_object->name == "app_object_4_test"
+    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
 
-.. php:trait:: TrackableTrait
+    The name will be unique within this container.
 
-    Trackable trait implements a few fields for the object that will maintain it's
-    relationship with the owner (parent).
+Properties
+----------
 
 .. php:attr:: 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.
 
-.. php:attr:: name
-
-    When name is set for container then all children will derrive their
-    name off the parent.
-
-    * Parent: foo
-    * Child:  foo_child1
-
-    The name will be unique within this container.
-
 .. php:attr:: short_name
 
-    When you add item into the owner, the "short_name" will 
+    When you add item into the owner, the "short_name" will contain short name of
+    this item.
+
+Methods
+-------
 
 .. php:meth:: getDesiredName
 
@@ -164,6 +206,6 @@ also receive unique "name". From example above:
 
 .. php:meth:: destroy
 
-    If object owners is set, then it will remove object from it's elements reducing
-    number of links to the object. Normally PHP's garbage collector should remove
-    object as soon as number of links is zero.
+    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.

docs/debug.rst

@@ -0,0 +1,17 @@
+===========
+Debug Trait
+===========
+
+.. php:trait:: DebugTrait
+
+Introduction
+============
+
+    not yet implemented
+
+Properties
+==========
+
+Methods
+=======
+

docs/dynamicmethod.rst

@@ -7,8 +7,6 @@ Dynamic Method Trait
 Introduction
 ============
 
-.. php:method:: addMethod($name, $callback)
-
 Adds ability to add methods into objects dynamically. That's like a "trait"
 feature of a PHP, but implemented in run-time::
 
@@ -20,7 +18,7 @@ Global Methods
 
 If object has application scope :php:trait:`AppScopeTrait` and the application
 implements :php:trait:`HookTrait` then executing $object->test() will also
-attempt look for globally-registered method inside the application::
+look for globally-registered method inside the application::
 
     $object->app->addGlobalMethod('test', function($app, $o, $args){
         echo 'hello, '.$args[0];
@@ -31,21 +29,49 @@ attempt look for globally-registered method inside the application::
 Of course calling test() on the other object afterwards will trigger same
 global method.
 
-If you attempt to register same method multiple times you will recevie
+If you attempt to register same method multiple times you will receive
 an exception.
 
 Dynamic Method Arguments
 ========================
-When calling dynamic methods the arguments are passed to the method,
-however an extra argument will be prepended equal to the object
-that this method was defined on::
+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
 
-.. php:method:: hasMethod
+Properties
+==========
+
+    None
+
+Methods
+=======
+
+.. php:method:: tryCall($method, $arguments)
+
+    Tries to call dynamic method, but doesn't throw exception if it is not possible.
+
+.. php:method:: addMethod($name, $callable)
+
+    Add new method for this object.
+    See examples above.
+
+.. php:method:: hasMethod($name)
+
+    Returns true if object has specified method (either native or dynamic).
+    Returns true also if specified methods is defined globally.
+
+.. php:method:: removeMethod($name)
+
+    Remove dynamically registered method.
+
+.. php:method:: addGlobalMethod($name, $callable)
+
+    Registers a globally-recognized method for all objects.
+
+.. php:method:: hasGlobalMethod($name)
 
-    will respond with true if method is defined either in the object
-    or globally.
+    Return true if such global method exists.