atk4/core

Core Traits for Agile Toolkit

Agile Toolkit - Web UI Toolkit

This is LEGACY version of Agile Toolkit. For a brand-new refactored alternative see http://agiletoolkit.org/

Agile Toolkit is a Web UI framework and collection of usable widgets. It allows you to develop rich web applications by writing only PHP code. Agile Toolkit is inspired by Desktop GUI Toolkits and is a fully-object oriented development environment.

• Homepage: http://agiletoolkit.org
• Forums: http://forum.agiletoolkit.org
• Docs: http://book.agiletoolkit.org

Overview

Agile Toolkit has introduced three new principles in web development:

• A Complete UI solution for PHP developers
• Unique integration between jQuery events and chains and PHP
• Innovative Object Relational Manager with support for joins, sub-selects and expression abstraction.

All the features are delivered in a unique close-coupled environment - Similarly to Cocoa or Qt - all objects of Agile Toolkit are based off one common ancestor and are constructed under the guidance of the top-level Application object.

Installing

To start a new web application in Agile Toolkit, download a bundle from http://agiletoolkit.org/ and follow instructions. Alternatively, if you are a very hardcore developer, add the following code inside your composer.json file:

"require": {
    "atk4/atk4": "4.3.*@dev"
}

Example

To help you understand some key principles of Agile Toolkit, copy the following example into page/index.php and place inside the init() method.

Source:

$form = $this->add('Form');
$form->addField('line', 'subject')->validateNotNull();
$form->addField('password','password');
$form->addSubmit();

if ($form->isSubmitted()) {
    $this->js()->univ()
        ->dialogOK('Hello World','Subject: '.$form['subject'])
        ->execute();
}

Congratulations. You have now created a fully AJAX / PHP form, fully protected from SQL / HTML / JS injection, based on jQuery UI theme and Bootstrap-compatible 12-column flexible grid system.

License

Agile Toolkit is distributed under MIT License.

Your support will ensure the longevity of Agile Toolkit

core's Issues

Configuration Elements cannot be replaced

If multiple configuration files are used, a configuration item cannot be replaced.
e.g. Standard Configuration with User Configuration.
default: $config['lang' => 'en'];
user: $config['lang' => 'de'];
Calling $obj->getConfig('lang') returns an array ['en', 'de'].
However, the string 'de' would be desired.
Is there a special reason why array_merge_recursive is used?
This can be prevented with array_replace_recursive.
Thanks in advance for an explanation.
See #117

Seed Refactoring

The usage of "Seed" throughout the framework have been a bit inconsistent. This needs to be reviewed. Here is proposal on how seed should work:

$seed = ['Class', 'arg1', 'arg2', 'property'=>$val];
$layout->add($seed);

this would be identical to:

$object = new Class('arg1', 'arg2');
$object->property=$val;
$layout->add($object);

Usage

This format would be respected throghout the framework, for example:

$layout->add(['Button', 'Label', 'red']);

For this to work correctly, constructor of Button() should accept arguments like this:

$button = new Button('Label', 'red');

Although it would require some refactoring, this approach would help with consistency. Another example is current implementation of TableColumn/Link:

$link = new \atk4\ui\TableColumn\Link($url, $args);

would, without hacking, translate into

$table->addColumn('name', ['Link', $url, $args]);

In other cases, if something is inconsistent, it needs to be adjusted. Here is example with addField:

$model->addField('age', ['type'=>'integer']);

Currently there is some custom logic there, but what we would have to do inside addfield:

function addField('name', $data) {
   if (!isset($data[0])) { $data[0] = $this->default_field_class; }
}

In other words, the new implementation would allow this:

$model->addField('image', ['ImageField', 'width'=>100, 'height'=>100]);

and actually could also give us alternative option to create reference:

$model->addField('country_id', ['Reference_One', 'model'=>new Country()]);

This is a major change across all of ATK and would require new releases to be coordinated.

Prefixing

The benefit of using seed is automated prefixing. For instance:

$form->addField('due', ['Money']);

When looking for the class, it will actually prefix 'Money' with 'FieldDecorator'. If any slashes are specified then no prefixing will take place.

When this is passed to the factory routine, it will prepend class name with '\atk4\ui' as well.

For user-defined classes, it's easier just to pass the object, while 3rd party add-ons may add more ways to prepend things, e.g. \thirdparty\bootstrap\FieldDecorator\Money.

mergeSeeds ignores arguments if already instanced

see

core/src/FactoryTrait.php

Line 37 in 5fb3fbe

$arguments = array_filter($seed2, 'is_numeric', ARRAY_FILTER_USE_KEY); // with numeric keys

$arguments are ignored. Of couse, they can not be passed to constructor anymore as already instanced, but shouln't this result in an exception?

PHPUnit 8.2.3 - strict_types

i run the test with phpunit 8 and get this error :

Testing started at 07:59 ...
/usr/bin/php /tmp/ide-phpunit.php --configuration /srv/nemesi/core/phpunit.xml
PHP Fatal error:  strict_types declaration must be the very first statement in the script in /srv/nemesi/core/vendor/phpunit/phpunit/phpunit on line 2
PHP Stack trace:
PHP   1. {main}() /tmp/ide-phpunit.php:0
PHP   2. IDE_PHPUnit_Loader::init() /tmp/ide-phpunit.php:250
PHP   3. IDE_PHPUnit_Loader::loadByAutoloader() /tmp/ide-phpunit.php:173

Process finished with exit code 255

The issue is know and probably will be solved.
https://www.reddit.com/r/PHP/comments/amp554/phpunit_8_with_php_72_is_out/

@romaninsh did you had this error?

Composer of develop branch not installable, tests are broken

See https://github.com/atk4/core/pull/133/checks?check_run_id=506766408

Every dev branch of atk4 repos should replace the 2.x version

See

core/composer.json

Line 45 in 313e372

"atk4/core": "self.version"

Important to fix all cases as mentioned by @DarkSide666 to make develop versions easily installable from custom projects with intermediate libraries, which requires otherwise stable version. Currently it is not possible to install them.

Symfony seems to be using branch-alias composer feature: https://github.com/twigphp/Twig/blob/3.x/composer.json#L46

Merge order should not change order of array seeds

This fails:

core/tests/SeedTest.php

Line 184 in 47c62bd

$this->assertEquals($oo, ['4'=>'four', '5'=>'five']);

if assertSame is used with the following diff:

4) atk4\core\tests\SeedTest::testMerge6
Failed asserting that two arrays are identical.
--- Expected
+++ Actual
@@ @@
 Array &0 (
+    4 => 'four'
     5 => 'five'
-    4 => 'four'
 )

/__w/core/core/tests/SeedTest.php:181
/__w/core/core/src/AtkPhpunit/TestCase.php:15

Allow/prioritize setter methods in DIContainerTrait::setDefaults()

core/src/DIContainerTrait.php

Line 50 in 503ed2f

public function setDefaults(array $properties, bool $passively = false)

proposal to call setXX() if exists instead of setting the XX property directly

Create static method for emitting deprecated warnings

See #133 (comment)

All deprecated code should emit deprecated warning/php notice to let the programmers notice the deprecations and force them to fix it asap.

If an Exception is thrown in a hook, the hook is not used any more after.

Hi there,

$model->addHook('beforeSave', function($m) {
    throw new \Exception('some exception');
});

try {
    $model->save();
}
catch(\Exception $e) {
    echo "Exception_found";
}
try {
    $model->save();
}
catch(\Exception $e) {
    echo "Exception_found";
}

Expected result: Exception_found is echoed 2 times,
Actual result: echoed only once, beforeSave hook isnt executed any more in second save().

The reason is in \atk4\core\HookTrait in function hook():
A while loop pops the array elements, and, some lines later, added again

while ($_data = array_pop($this->hooks[$hook_spot])) {
....
$this->hooks[$hook_spot] = $hook_backup;

If an exception is thrown in between these lines, $this->hooks[$hook_spot] is not "filled" again.

A simple fix is to not pop the array elements but leave as is, e.g.

try {
            if (
                isset($this->hooks[$hook_spot])
                && is_array($this->hooks[$hook_spot])
            ) {
                krsort($this->hooks[$hook_spot]); // lower priority is called sooner
                $hook_backup = $this->hooks[$hook_spot];
                foreach($this->hooks[$hook_spot] as $_data) {
                    foreach ($_data as &$data) {
                        $return[] = call_user_func_array(
                            $data[0],
                            array_merge(
                                [$this],
                                $arg,
                                $data[1]
                            )
                        );
                    }
                }
            }
        } catch (HookBreaker $e) {
            return $e->return_value;
        }

Version of atk4/core for atk4/ui:2.1.0 needed

A new version for atk4/ui 2.1.0 was released a few days ago.
There is a new version atk4/core needed to use this version.
Is there a release planned in the near future (I really would need that version of ui...)

factory() - ability to specify prefix

currently factory accepts seed and defaults, but it should also accept class prefix.

Show relative file paths in error trace

• show relative paths to the project/composer root
• do not shorten long paths (currently, there is some limit, even no ellipse char "..." is prepended)

Check type from phpdoc when seeding

Extremely important to support seeds with at least some checking.

When hook for the same spot is added from hook itself, it is removed once the hook finish

core/src/HookTrait.php

Line 186 in 0d922e0

$this->hooks[$spot] = $hookBackup;

Is this desired and why?

Hook break can not be detected

See

core/src/HookTrait.php

Line 156 in 2d72fed

return $e->return_value;

Currently, if breaker returns an array the break by hook breaker can not be detected.

Why not to throw an exception? If circuit breaker is desired, it should alway return an array and reference parameter like bool &$wasInterrupted should be added to the hook execution method. Or return an CircuitBreaker object?

Add localization support/strings

So need to establish a standard way how to add translations and create initial file(s) for atk4/core project strings.

As a test - verify that local messages are properly translated if the language is set.

ContainerTrait and TrackableTrait define the same property ($name)

$ phpunit
PHP Strict standards: atk4\core\ContainerTrait and atk4\core\TrackableTrait define the same property ($name) in the composition of atk4\core\tests\ContainerAppMock. This might be incompatible, to improve maintainability consider using accessor methods in traits instead. Class was composed in /home/travis/build/atk4/core/tests/ContainerTraitTest.php on line 188
PHP Stack trace:
PHP 1. {main}() /home/travis/.phpenv/versions/5.6.23/bin/phpunit:0
PHP 2. PHPUnit_TextUI_Command::main() /home/travis/.phpenv/versions/5.6.23/bin/phpunit:569
PHP 3. PHPUnit_TextUI_Command->run() phar:///home/travis/.phpenv/versions/5.6.23/bin/phpunit/phpunit/TextUI/Command.php:113
PHP 4. PHPUnit_TextUI_Command->handleArguments() phar:///home/travis/.phpenv/versions/5.6.23/bin/phpunit/phpunit/TextUI/Command.php:124
PHP 5. PHPUnit_Util_Configuration->getTestSuiteConfiguration() phar:///home/travis/.phpenv/versions/5.6.23/bin/phpunit/phpunit/TextUI/Command.php:745
PHP 6. PHPUnit_Util_Configuration->getTestSuite() phar:///home/travis/.phpenv/versions/5.6.23/bin/phpunit/phpunit/Util/Configuration.php:852
PHP 7. PHPUnit_Framework_TestSuite->addTestFiles() phar:///home/travis/.phpenv/versions/5.6.23/bin/phpunit/phpunit/Util/Configuration.php:941
PHP 8. PHPUnit_Framework_TestSuite->addTestFile() phar:///home/travis/.phpenv/versions/5.6.23/bin/phpunit/phpunit/Framework/TestSuite.php:413
PHP 9. PHPUnit_Util_Fileloader::checkAndLoad() phar:///home/travis/.phpenv/versions/5.6.23/bin/phpunit/phpunit/Framework/TestSuite.php:339
PHP 10. PHPUnit_Util_Fileloader::load() phar:///home/travis/.phpenv/versions/5.6.23/bin/phpunit/phpunit/Util/Fileloader.php:38
PHP 11. include_once() phar:///home/travis/.phpenv/versions/5.6.23/bin/phpunit/phpunit/Util/Fileloader.php:56
Strict standards: atk4\core\ContainerTrait and atk4\core\TrackableTrait define the same property ($name) in the composition of atk4\core\tests\ContainerAppMock. This might be incompatible, to improve maintainability consider using accessor methods in traits instead. Class was composed in /home/travis/build/atk4/core/tests/ContainerTraitTest.php on line 188

Add documentation on how to use PHPunit extensions.

printerClass="atk4\core\PHPUnit_AgileResultPrinter"

Require numerical keys in any seed to be always in 0..n format without holes

Why? Robustness. It would prevent a lot of unwanted issues.

It needs to be evaluated on major repos if it is not too strict.

MergeSeeds don't respect numeric keys defined as strings

Example:

$years = ['2013', '2014'];
$a = new Object(['years'=>$years]);
var_dump($a->years); // returns [0=>'2013', 1=>'2014']

That's because is_numeric('123')===true. Must use is_int('123')===false almost everywhere.

In here:
https://github.com/atk4/core/blob/develop/src/FactoryTrait.php#L38
https://github.com/atk4/core/blob/develop/src/FactoryTrait.php#L59

Also is_numeric is quite widely used in DIContainer and in data, dsql and ui repositories. Need to review them too.

Fallback decorator properties

https://github.com/atk4/ui/blob/9f39eab2dbeb177a0920e555dc1d7ddbf8ec954c/src/Form.php#L479

Fallback decorator properties cause 'trying to set missing property' exception when the custom set decorator class does not have the same properties.
E.g if fallback decorator is DropDown the seed gets assigned values key. But if the custom set decorator does not have values property then exception is thrown as when merging of seeds is done the 'values' key is preserved in the final seed.

Port "addSolution" to atk core Exceptions and UI

be considerate of #93 ..

https://github.com/atk4/atk4/blob/4.4/lib/BaseException.php#L137

DebugTrait misses log() and warn() methods

As per documentation:

$object->log('something happened');
$object->warn('bad things happen');

but currently there are no such methods in DebugTrait.

Improve tests coverage

Idea: Seed to support hooks.

Currently hooks support properties:

$this->factory([Some::class, 'jsCallback'=>function() {});

However it's not important to inject hooks! The idea is to extend factory support to allow placement of hooks through factory:

$this->factory([Some::class, 'hook:afterExecute'=>[ function(){} ]);

When merging seeds, hooks will be also combined, since we support hooks well. Also we can introduce advanced syntax if hook priority should be specified inside hook array.

Exception: rename addMoreInfo() into addParam()

Hi,

this is just a minor minor one. I think the method addMoreInfo() should be renamed to addParam(), as this is what it really does. This would make the name consistent with getParams() and params property.

Best regards
Philipp

undocumented method

https://github.com/atk4/core/blob/develop/src/Exception.php#L152

getHTML is not documented i believe.

Checklist

Implemented

ContainerTrait

• implemented
• docs
• tests

TrackableTrait

• implemented
• docs
• tests

NameTrait

• implemented
• docs

InitializerTrait

• implemented
• docs
• tests

DynamicMethodTrait

• implemented
• docs
• tests

HookTrait

• implemented
• docs
• tests

AppScopeTrait

• implemented
• docs

FactoryTrait

• implemented
• docs
• tests

Exception

• implemented
• docs
• tests
• refactor by moving getColorfulMessage outside of exception

Version 1.2

QuickExceptionTrait - improves backtrace and helps object add essential data into exceptions on

• implemented
• docs
• tests

DebugTrait - allows to switch debug in object or app or hide it.

• implemented
• docs
• tests

Possibly outside of scope

SessionTrait

• implemented
• docs
• tests

Renderable

more..

Exception is not capturing objects

For ATK capturing backtrace using the object references is much more meaningful, because it allows the dumper to collect object names.

Open Codecov links from GH check to public

Currently links from Codecov checks are not viewable for anyone except admin, even maintainers can not access the stats.

It is important to be able to open more details if check failed. For every repo.

assertRegExp() is deprecated and will be removed in PHPUnit 10. Refactor your code to use assertMatchesRegularExpression() instead.

There are several warnings in current tests which needs to be fixed/refactored.

see https://github.com/atk4/core/runs/573845743#step:10:15

Need to have universal constructor trait

    function __construct($options = []) {
        if(is_array($options)) {
            foreach($options as $key=>$val) {
                if($val !== null) $this->$key = $val;
            }
        }
    }

This code is appearing too often, so we should probably consolidate it into a trait.

Multiple hooks for one action can be added, but they have to be currently deleted completely

See https://github.com/atk4/core/blob/develop/src/HookTrait.php#L98

Specific hook should be possible to delete by name and priority.

Injecting "null" argument into constructor fails

Suppose you create a button using a seed:

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

it is created with no label and with an icon. Next consider this code:

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

This works as expected. Button with label and icon is added. Next try this:

$button = $app->add(['Button', 'lablabla', 'big red', 'icon'=>'book']);

once again, this works as expected. A big red button with label and icon is added.

Now suppose you want to get rid of label, so you replace it with null

$button = $app->add(['Button', null, 'big red', 'icon'=>'book']);

But instead you find with a small button and label "big red".

A current workaround is to specify 2nd argument as "false" or empty string but I think null should be equally acceptable.

refactor to use instanceOf instead of isset(_appScopeTrait)

For some weird reason initial implementation uses code that relies on presence of specific properties in the class in order to detect a trait.

If this can be refactored, then there would be less warnings and cleaner code:

There are many occurrences, please create PR and make sure test-suite still works.

ConfigTrait _lookConfigElement throw error when request deep ref and not found

core/src/ConfigTrait.php

Line 163 in c16bb75

if (!array_key_exists($el, $pos) && $create_elements) {

throw error : array_key_exists 2nd argument must be array

$this->config = [
'test' => 'something'
];

$this->getConfig('test/deep'); // <-- throw error

can we add a check if $pos is_array?

if(!is_array($pos))
{
return false;
}

Review docs/factory.rst seed merging section

Need to review and fix docs/factory.rst and especially paragraph about seed merging.

Created as a followup for #67

Render text exception before HTML

HTML is hard to read, render exception in plain text before HTML

Exception constructor trace should be never stored at all

Improve #188

@DarkSide666 ok?

compare trace of new Exception() and new \Exception(), the later has not __construct trace.

Current example:

Undefined factory defaults shouldn't throw exception.

Calling factory like this:

$m1 = $m->factory('atk4\core\tests\FactoryMock', ['not_exist'=>'test']);

may encounter some parameters that are not defined in the class. Instead of throwing exception we are going to silently ignore them for a few reasons:

• Agile UI redefines this to bring class support
• 'desired_name' is used for name hinting and it's not a real property
• component may remove support for feature which shouldn't trigger exception

So we are disabling this check.

UPDATE: in v1.3, I'm reversing this decision, in favour of clean code. This will require some refactor of UI / Data libraries though, but we have to do it anyway

Use mb_ functions

Check if we have any of these methods and if so,then use their mb_ equivalent.
http://php.net/manual/en/ref.mbstring.php

Particularly test:

• passing utf8 values as parameters paramns from exceptions
• ..

Add docs for ConfigTrait

ConfigTrait was implemented here #86, but there are no docs for it.

Generate doc from PHP

If the doc can not be kept up-to-date, it is useless and should be reduced/removed or self-generated from the actual code - and I prefer it.

I personally use PHP source as doc directly.

• generate the doc for web-only, ie. remove it from repo
• do it for all repos

Display where \Closure was defined in exception trace

Very important for fast debug and even more important in Atk, where closures/callbacks are used a lot.

Location can be obtained via Reflection.

Example:

DynamicMethodTrait__call: Add method name to Exception

Hello,

this is a typical PHPUnit output:

1) BookingTest::testDiscountCodeMToM
atk4\core\Exception: Method is not defined for this object

Of course, having the method name in the exception message would help a lot, like

1) BookingTest::testDiscountCodeMToM
atk4\core\Exception: Method myNonExsistantMethod is not defined for this object

If no one objects, I would implement this, its a very simple adjustment in DynamicMethodTrait->__call().

Test ticket from Code Climate

It should be possible to add hooks that do not require the source object as 1st param

Example of bad but typical usage:

Example of better but still not good usage:

Example of good usage:

Adding object twice

When an object is already added into the container, adding it again may cause some problems (e.g. maybe same ID, or project needs additional initialization).

One scenario would be if you create field object, add to one form then add to another one, what should happen? Or if you take field from one model and add it into another?

History

Initially, this was permitted and init() would be called again when added the second time.

In #41 we added protection preventing from second initialization, but it created some problems.

In #48 we changed so that init() is not called the second time.

Ideas

When adding the existing object into another container, call attach() method.

add documentation mentioning Exception::getHTML

didn't have time to implement it right away, but must add.