From cd555bb06d48d6f80d4064cd3ccf4cb74555164d Mon Sep 17 00:00:00 2001 From: Giuseppe Mazzapica Date: Sun, 25 Jan 2015 02:29:04 +0100 Subject: [PATCH] Cleanup: typos, doc block, CS --- docs/DATA/ARRAIZATION.md | 2 +- docs/EXTENDING/CUSTOM-EXTENSIONS.md | 2 +- docs/INTEGRATE/API.md | 10 +++---- docs/TEMPLATES/INHERITANCE.md | 4 +-- inc/functions.php | 17 ++++++----- src/Contracts/EngineInterface.php | 7 ++--- src/Engine.php | 4 +-- src/Extensions/Helpers.php | 10 +++---- src/Extensions/Links.php | 6 ++-- src/Extensions/Uri.php | 4 +-- src/Kernel/Arraize.php | 14 ++++----- src/Kernel/Command.php | 2 +- src/Providers/Context.php | 2 +- src/Providers/Kernel.php | 46 ++++++++++++++++------------- src/Section/Factory.php | 2 +- src/Template/Factory.php | 2 +- src/Template/Finder.php | 8 ++--- src/Template/Stack.php | 1 - src/Template/Template.php | 5 ++-- src/Traits/APIAwareTrait.php | 3 ++ src/Traits/EngineAwareTrait.php | 3 ++ src/Traits/FinderAwareTrait.php | 7 +++++ src/Traits/TemplateAwareTrait.php | 6 ++++ 23 files changed, 97 insertions(+), 70 deletions(-) diff --git a/docs/DATA/ARRAIZATION.md b/docs/DATA/ARRAIZATION.md index 5e4ba34..c7fc30c 100644 --- a/docs/DATA/ARRAIZATION.md +++ b/docs/DATA/ARRAIZATION.md @@ -64,7 +64,7 @@ To use transformers you need to pass to `arraize()` an associative array where - keys are the fully-qualified class names of the objects to be transformed - values are the tranformers to apply -Tranformers (the array values) can be passed in 3 ways: +Transformers (the array values) can be passed in 3 ways: - as callbacks that receive the object and have to return an array - as object instances, that don't need to implement any interface or extend any class, they just need a method `transform()` that receives the object and has to return an array diff --git a/docs/EXTENDING/CUSTOM-EXTENSIONS.md b/docs/EXTENDING/CUSTOM-EXTENSIONS.md index 05e538a..911a392 100644 --- a/docs/EXTENDING/CUSTOM-EXTENSIONS.md +++ b/docs/EXTENDING/CUSTOM-EXTENSIONS.md @@ -76,7 +76,7 @@ Second argument passed to `loadExtension()` is the array that will passed to `se As better explained in the *"Extending Foil / Custom Functions & Filters"* Foil functions by default can't output HTML content, because their output is HTML-encoded. -When you register a single functions via `$engine->registerfunction()` is possible to pass `true` as 3rd argument to mark the function as *safe* so that it is allowed to output HTML. +When you register a single functions via `$engine->registerFunction()` is possible to pass `true` as 3rd argument to mark the function as *safe* so that it is allowed to output HTML. When you load an extension that provides functions that needs to output HTML, you need to register those function as safe as well. diff --git a/docs/INTEGRATE/API.md b/docs/INTEGRATE/API.md index cfcb0e4..ce916fe 100644 --- a/docs/INTEGRATE/API.md +++ b/docs/INTEGRATE/API.md @@ -217,14 +217,14 @@ Any other data type will be returned unchanged. ```php /** -* @param mixed $data Data to convert -* @param bool $escape Should strings in data be HTML-encoded? -* @param array $trasformers Transformers: full qualified class names, objects or callables -* @param bool $tostring Should all scalar items be casted to strings? +* @param mixed $data Data to convert +* @param bool $escape Should strings in data be HTML-encoded? +* @param array $transformers Transformers: full qualified class names, objects or callables +* @param bool $tostring Should all scalar items be casted to strings? * @return array */ -function arraize($data = [], $escape = false, array $trasformers = [], $tostring = false) +function arraize($data = [], $escape = false, array $transformers = [], $tostring = false) ``` This function allow to recursively convert to array any kind of data. It is a powerful tool, and there is an entire doc page that explain how it work and how to use it. diff --git a/docs/TEMPLATES/INHERITANCE.md b/docs/TEMPLATES/INHERITANCE.md index cb68e31..ca2a4b1 100644 --- a/docs/TEMPLATES/INHERITANCE.md +++ b/docs/TEMPLATES/INHERITANCE.md @@ -32,7 +32,7 @@ Let's define a base layout, `main.php`, which defines a simple HTML skeleton doc section('head') ?> - <?php $this->section('title') ?>My Webpage<?php $this->stop() ?> + <?php $this->section('title') ?>My Home Page<?php $this->stop() ?> stop() ?> @@ -81,7 +81,7 @@ E.g. if the child template above is rendered, `` tag will contain: ```html - My Webpage + My Home Page diff --git a/inc/functions.php b/inc/functions.php index b925755..73ae59e 100644 --- a/inc/functions.php +++ b/inc/functions.php @@ -25,7 +25,9 @@ use Foil\Context\SearchContext; use Foil\Context\RegexContext; use Foil\Context\GlobalContext; +use Foil\Contracts\ContextInterface; use Foil\Kernel\Arraize; +use Traversable; use LogicException; use InvalidArgumentException; @@ -88,7 +90,7 @@ function engine(array $options = []) * When used before any engine() call, is possible to set engine options. * * @param string $path Full path for the template - * @param array $data Template contex + * @param array $data Template context * @param array $options Options for the engine * @return string */ @@ -196,6 +198,7 @@ function fire($event) * * @param string $event * @param callable $callback + * @param bool $once */ function on($event, callable $callback, $once = false) { @@ -279,14 +282,14 @@ function decode($data) * - if the is an instance of JsonSerializable it is JSON-encoded then decoded * - calling get_object_vars() * - * @param mixed $data Data to convert - * @param bool $escape Should strings in data be HTML-encoded? - * @param array $trasformers Transformers: full qualified class names, objects or callables - * @param bool $tostring Should all scalar items in data be casted to strings? + * @param mixed $data Data to convert + * @param bool $escape Should strings in data be HTML-encoded? + * @param array $transformers Transformers: full qualified class names, objects or callables + * @param bool $tostring Should all scalar items in data be casted to strings? * @return array */ - function arraize($data = [], $escape = false, array $trasformers = [], $tostring = false) + function arraize($data = [], $escape = false, array $transformers = [], $tostring = false) { - return (new Arraize())->run($data, $escape, $trasformers, $tostring); + return (new Arraize())->run($data, $escape, $transformers, $tostring); } } diff --git a/src/Contracts/EngineInterface.php b/src/Contracts/EngineInterface.php index f3d9ee2..bde0e68 100644 --- a/src/Contracts/EngineInterface.php +++ b/src/Contracts/EngineInterface.php @@ -16,10 +16,10 @@ interface EngineInterface const STATUS_IN_PARTIAL = 16; /** - * Find a template fullpath for a given template name. + * Find a template full path for a given template name. * Templates will be searched in all registered folders. * If extension is not given default one is added. - * File with matching names but not accepeted exceptions will be skipped. + * File with matching names but not accepted exceptions will be skipped. * * @param string $template */ @@ -79,8 +79,7 @@ public function setFolders(array $folders); /** * Get engine status * - * @param string $status - * @return int One of the statues constants + * @return int One of the statues constants */ public function status(); } diff --git a/src/Engine.php b/src/Engine.php index 14b1376..be6a6a2 100644 --- a/src/Engine.php +++ b/src/Engine.php @@ -117,10 +117,10 @@ public function setFolders(array $folders) * call templates from there. * * @param string $path - * @param string $name + * @param string|void $name * @return \Foil\Engine */ - public function addFolder($path, $name = 0) + public function addFolder($path, $name = null) { $this->finder()->in([$name => $path]); diff --git a/src/Extensions/Helpers.php b/src/Extensions/Helpers.php index 5dd5c08..2ac513e 100644 --- a/src/Extensions/Helpers.php +++ b/src/Extensions/Helpers.php @@ -65,7 +65,7 @@ public function provideFunctions() * * @param string $var Variable name * @param mixed $default Default - * @param string|array $filter Array or pipe-separed list of filters + * @param string|array $filter Array or pipe-separated list of filters * @return mixed */ public function variable($var, $default = '', $filter = null) @@ -81,7 +81,7 @@ public function variable($var, $default = '', $filter = null) * * @param string $var Variable name * @param mixed $default Default - * @param string|array $filter Array or pipe-separed list of filters + * @param string|array $filter Array or pipe-separated list of filters * @return mixed */ public function escape($var, $default = '', $filter = null) @@ -95,7 +95,7 @@ public function escape($var, $default = '', $filter = null) * * @param string $var Variable name * @param mixed $default Default - * @param string|array $filter Array or pipe-separed list of filters + * @param string|array $filter Array or pipe-separated list of filters * @return mixed */ public function decode($var, $default = '', $filter = null) @@ -108,7 +108,7 @@ public function decode($var, $default = '', $filter = null) * * @param string $var Variable name * @param mixed $default Default - * @param string|array $filter Array or pipe-separed list of filters + * @param string|array $filter Array or pipe-separated list of filters * @return mixed */ public function raw($var, $default = '', $filter = null) @@ -153,7 +153,7 @@ public function asArray($var, $default = [], $filter = null, $force_raw = false) * * @param string $var Variable name * @param mixed $default Default - * @param string|array $filter Array or pipe-separed list of filters + * @param string|array $filter Array or pipe-separated list of filters * @return mixed */ public function asArrayRaw($var, $default = [], $filter = null) diff --git a/src/Extensions/Links.php b/src/Extensions/Links.php index 2537e4b..78e3d3c 100644 --- a/src/Extensions/Links.php +++ b/src/Extensions/Links.php @@ -49,9 +49,9 @@ public function provideFunctions() * Return a relative (or absolute if a host is set) url for a file whose directory has been * set via setup arguments. Allow to easily output long urls with few chars. * - * @param string $file - * @param string $subdir_url - * @param boolean $use_scheme + * @param string $file + * @param string|bool $subdir_url + * @param boolean $use_scheme * @return string */ public function link($file, $subdir_url = false, $use_scheme = null) diff --git a/src/Extensions/Uri.php b/src/Extensions/Uri.php index 464f2ea..51c846d 100644 --- a/src/Extensions/Uri.php +++ b/src/Extensions/Uri.php @@ -56,9 +56,9 @@ public function provideFunctions() public function is($url = '', $if_true = true, $if_false = "") { if (is_array($url) && isset($url[0]) && is_int($url[0]) && $url[0] <= count($this->chunks)) { - $chunch = isset($url[1]) && is_string($url[1]) ? $this->clean($url[1]) : ''; + $chunk = isset($url[1]) && is_string($url[1]) ? $this->clean($url[1]) : ''; - return $this->clean($this->chunks[($url[0] - 1)]) === $chunch ? $if_true : $if_false; + return $this->clean($this->chunks[($url[0] - 1)]) === $chunk ? $if_true : $if_false; } return $this->clean($this->path) === $this->clean($url) ? $if_true : $if_false; diff --git a/src/Kernel/Arraize.php b/src/Kernel/Arraize.php index 2106b33..add2b6b 100644 --- a/src/Kernel/Arraize.php +++ b/src/Kernel/Arraize.php @@ -29,7 +29,7 @@ class Arraize /** * @param mixed $data Data to convert * @param bool $escape Should strings in data be HTML-encoded? - * @param array $trasf Transformes: full qualified class names, objects or callables + * @param array $trasf Transformers: full qualified class names, objects or callables * @param bool $tostring Should all scalar items in data be casted to strings? * @return array */ @@ -93,7 +93,7 @@ private function walk($var, $flags, $trasf) */ private function transform($var, $class, $trasf) { - $cb = $this->trasformer(isset($trasf[trim($class, '\\')]) ? $trasf[$class] : false); + $cb = $this->transformer(isset($trasf[trim($class, '\\')]) ? $trasf[$class] : false); if (is_object($cb) && method_exists($cb, 'transform')) { $cb = [$cb, 'transform']; @@ -103,16 +103,16 @@ private function transform($var, $class, $trasf) } /** - * @param mixed $trasformer + * @param mixed $transformer * @return callable|object|bool */ - private function trasformer($trasformer) + private function transformer($transformer) { - if (is_string($trasformer) && class_exists($trasformer)) { - $trasformer = new $trasformer(); + if (is_string($transformer) && class_exists($transformer)) { + $transformer = new $transformer(); } - return is_object($trasformer) || is_callable($trasformer) ? $trasformer : false; + return is_object($transformer) || is_callable($transformer) ? $transformer : false; } /** diff --git a/src/Kernel/Command.php b/src/Kernel/Command.php index 231ccd0..790adae 100644 --- a/src/Kernel/Command.php +++ b/src/Kernel/Command.php @@ -6,7 +6,7 @@ /** * Class that holds all the functions and filters registered in extensions. - * It handle all unexistent methods called on temmplate objects inside template files. + * It handle all non-existent methods called on template objects inside template files. * * @author Giuseppe Mazzapica * @package foil\foil diff --git a/src/Providers/Context.php b/src/Providers/Context.php index 5b70632..374874c 100644 --- a/src/Providers/Context.php +++ b/src/Providers/Context.php @@ -65,7 +65,7 @@ private function engineAddData(ContextCollection $collection, $args) private function engineAddContext(ContextCollection $collection, $args) { if ($args[0] instanceof ContextInterface) { - return $collection->add($args[0]); + $collection->add($args[0]); } if (is_string($args[0]) && isset($args[1]) && is_array($args[1])) { $is_regex = isset($args[2]) && ! empty($args[2]); diff --git a/src/Providers/Kernel.php b/src/Providers/Kernel.php index 4e5543f..4cae155 100644 --- a/src/Providers/Kernel.php +++ b/src/Providers/Kernel.php @@ -43,29 +43,35 @@ public function register(Container $container) public function boot(Container $container) { // register an extension - $container['events']->on('f.extension.load', function (Extension $extension, array $options, $safe) use ($container) { - $extension->setup($options); - $container['command']->registerFunctions($extension->provideFunctions(), $safe); - $container['command']->registerFilters($extension->provideFilters()); - if ($extension instanceof TemplateAware) { - $extension->setStack($container['template.stack']); + $container['events']->on( + 'f.extension.load', + function (Extension $extension, array $options, $safe) use ($container) { + $extension->setup($options); + $container['command']->registerFunctions($extension->provideFunctions(), $safe); + $container['command']->registerFilters($extension->provideFilters()); + if ($extension instanceof TemplateAware) { + $extension->setStack($container['template.stack']); + } + if ($extension instanceof FinderAware) { + $extension->setFinder($container['template.finder']); + } + if ($extension instanceof APIAware) { + $extension->setAPI($container['api']); + } + if ($extension instanceof EngineAware) { + $extension->setEngine($container['engine']); + } + $container['events']->fire('f.extension.registered', $extension); } - if ($extension instanceof FinderAware) { - $extension->setFinder($container['template.finder']); - } - if ($extension instanceof APIAware) { - $extension->setAPI($container['api']); - } - if ($extension instanceof EngineAware) { - $extension->setEngine($container['engine']); - } - $container['events']->fire('f.extension.registered', $extension); - }); + ); // register an function - $container['events']->on('f.function.register', function ($function, callable $callback, $safe) use ($container) { - $container['command']->registerFunctions([$function => $callback], $safe); - }); + $container['events']->on( + 'f.function.register', + function ($function, callable $callback, $safe) use ($container) { + $container['command']->registerFunctions([$function => $callback], $safe); + } + ); // register a filter $container['events']->on('f.filter.register', function ($filter, callable $callback) use ($container) { diff --git a/src/Section/Factory.php b/src/Section/Factory.php index 8a245ea..be7b810 100644 --- a/src/Section/Factory.php +++ b/src/Section/Factory.php @@ -34,7 +34,7 @@ public function __construct(ArrayAccess $sections, $default_mode = null, $contra * Factory a section instance (if it was not already factored) and return it. * * @param string $name Section name - * @param int $mode Section mode, one of the mode const + * @param int|bool $mode Section mode, one of the mode const * @param string $class_name Full qualified section class name * @return \Foil\Contracts\SectionInterface * @throws InvalidArgumentException diff --git a/src/Template/Factory.php b/src/Template/Factory.php index c6b2197..a956247 100644 --- a/src/Template/Factory.php +++ b/src/Template/Factory.php @@ -38,7 +38,7 @@ public function __construct(AA $templates, AA $sections, API $api, $contract = n /** * Factory and/or returns template objects. * - * @param string $path Fullpath to template file + * @param string $path Full path to template file * @param string $class_name A custom template class name * @return \Foil\Contracts\TemplateInterface * @throws InvalidArgumentException diff --git a/src/Template/Finder.php b/src/Template/Finder.php index 16b8c5b..b5ce9c0 100644 --- a/src/Template/Finder.php +++ b/src/Template/Finder.php @@ -82,9 +82,9 @@ public function dirs() } /** - * Takes a template name and looks for directory name passed in Foil convenction, that is + * Takes a template name and looks for directory name passed in Foil convention, that is * folder_name::file_name. - * If file name as no extension, defauld estension is appendended if available. + * If file name as no extension, default extension is appended if available. * * @param string $template_name * @return array @@ -109,8 +109,8 @@ private function parseName($template_name) /** * Find a template when a specific directory name is required * - * @param type $dir - * @param type $template_name + * @param string $dir + * @param string $template_name * @return boolean */ private function findInDir($dir, $template_name) diff --git a/src/Template/Stack.php b/src/Template/Stack.php index a9b1bd2..bd272b9 100644 --- a/src/Template/Stack.php +++ b/src/Template/Stack.php @@ -64,7 +64,6 @@ public function pop() /** * Returns the count of templates in the stack. * - * @param string $mode * @return int */ public function count() diff --git a/src/Template/Template.php b/src/Template/Template.php index 6910e7e..2c04fc2 100644 --- a/src/Template/Template.php +++ b/src/Template/Template.php @@ -32,7 +32,7 @@ public function __construct($path, ArrayAccess $sections, API $api) } /** - * Proxies inexistent methods to command to call registered extensions functions + * Proxies non-existent methods to command to call registered extensions functions * * @param string $name * @param array $arguments @@ -124,7 +124,8 @@ public function render(array $data = []) while ($this->layoutPath()) { $layout = $this->layoutPath(); $this->setData($this->buildContext( - $this->layout_data[$layout]['data'], $this->layout_data[$layout]['only'] + $this->layout_data[$layout]['data'], + $this->layout_data[$layout]['only'] )); $this->layout = null; // listener for this event makes sections work in output mode diff --git a/src/Traits/APIAwareTrait.php b/src/Traits/APIAwareTrait.php index 2fae1bc..e4f79bd 100644 --- a/src/Traits/APIAwareTrait.php +++ b/src/Traits/APIAwareTrait.php @@ -11,6 +11,9 @@ trait APIAwareTrait { private $api; + /** + * @return API + */ public function api() { return $this->api; diff --git a/src/Traits/EngineAwareTrait.php b/src/Traits/EngineAwareTrait.php index d9da2b2..68b8b2f 100644 --- a/src/Traits/EngineAwareTrait.php +++ b/src/Traits/EngineAwareTrait.php @@ -11,6 +11,9 @@ trait EngineAwareTrait { private $engine; + /** + * @return EngineInterface + */ public function engine() { return $this->engine; diff --git a/src/Traits/FinderAwareTrait.php b/src/Traits/FinderAwareTrait.php index 12b3101..403704f 100644 --- a/src/Traits/FinderAwareTrait.php +++ b/src/Traits/FinderAwareTrait.php @@ -11,11 +11,18 @@ trait FinderAwareTrait { private $finder; + /** + * @return Finder + */ public function finder() { return $this->finder; } + /** + * @param string $template + * @return bool|string + */ public function find($template) { return $this->finder()->find($template); diff --git a/src/Traits/TemplateAwareTrait.php b/src/Traits/TemplateAwareTrait.php index 4b89172..d618904 100644 --- a/src/Traits/TemplateAwareTrait.php +++ b/src/Traits/TemplateAwareTrait.php @@ -11,6 +11,9 @@ trait TemplateAwareTrait { private $stack; + /** + * @return Stack + */ public function stack() { return $this->stack; @@ -21,6 +24,9 @@ public function setStack(Stack $stack) $this->stack = $stack; } + /** + * @return \Foil\Contracts\TemplateInterface + */ public function template() { return $this->stack()->template();