diff --git a/flight/Engine.php b/flight/Engine.php index f8c996b..3406081 100644 --- a/flight/Engine.php +++ b/flight/Engine.php @@ -40,7 +40,7 @@ use Throwable; * Request-response * @method Request request() Gets current request * @method Response response() Gets current response - * @method void error(Exception $e) Sends an HTTP 500 response for any errors. + * @method void error(Throwable $e) Sends an HTTP 500 response for any errors. * @method void notFound() Sends an HTTP 404 response when a URL is not found. * @method void redirect(string $url, int $code = 303) Redirects the current request to another URL. * @method void json(mixed $data, int $code = 200, bool $encode = true, string $charset = 'utf-8', int $option = 0) Sends a JSON response. @@ -54,6 +54,7 @@ class Engine { /** * Stored variables. + * @var array */ protected array $vars; @@ -84,7 +85,7 @@ class Engine * Handles calls to class methods. * * @param string $name Method name - * @param array $params Method parameters + * @param array $params Method parameters * * @throws Exception * @@ -155,8 +156,8 @@ class Engine $this->before('start', function () use ($self) { // Enable error handling if ($self->get('flight.handle_errors')) { - set_error_handler([$self, 'handleError']); - set_exception_handler([$self, 'handleException']); + set_error_handler(array($self, 'handleError')); + set_exception_handler(array($self, 'handleException')); } // Set case-sensitivity @@ -177,18 +178,21 @@ class Engine * @param int $errline Error file line number * * @throws ErrorException + * @return bool */ public function handleError(int $errno, string $errstr, string $errfile, int $errline) { if ($errno & error_reporting()) { throw new ErrorException($errstr, $errno, 0, $errfile, $errline); } + + return false; } /** * Custom exception handler. Logs exceptions. * - * @param Exception $e Thrown exception + * @param Throwable $e Thrown exception */ public function handleException($e): void { @@ -203,7 +207,7 @@ class Engine * Maps a callback to a framework method. * * @param string $name Method name - * @param callback $callback Callback function + * @param callable $callback Callback function * * @throws Exception If trying to map over a framework method */ @@ -218,11 +222,12 @@ class Engine /** * Registers a class to a framework method. + * @template T of object * * @param string $name Method name - * @param string $class Class name - * @param array $params Class initialization parameters - * @param callable|null $callback $callback Function to call after object instantiation + * @param class-string $class Class name + * @param array $params Class initialization parameters + * @param ?callable(T $instance): void $callback Function to call after object instantiation * * @throws Exception If trying to map over a framework method */ @@ -239,7 +244,7 @@ class Engine * Adds a pre-filter to a method. * * @param string $name Method name - * @param callback $callback Callback function + * @param callable $callback Callback function */ public function before(string $name, callable $callback): void { @@ -250,7 +255,7 @@ class Engine * Adds a post-filter to a method. * * @param string $name Method name - * @param callback $callback Callback function + * @param callable $callback Callback function */ public function after(string $name, callable $callback): void { @@ -437,7 +442,7 @@ class Engine * Routes a URL to a callback function. * * @param string $pattern URL pattern to match - * @param callback $callback Callback function + * @param callable $callback Callback function * @param bool $pass_route Pass the matching route object to the callback */ public function _route(string $pattern, callable $callback, bool $pass_route = false): void @@ -449,7 +454,7 @@ class Engine * Routes a URL to a callback function. * * @param string $pattern URL pattern to match - * @param callback $callback Callback function + * @param callable $callback Callback function * @param bool $pass_route Pass the matching route object to the callback */ public function _post(string $pattern, callable $callback, bool $pass_route = false): void @@ -461,7 +466,7 @@ class Engine * Routes a URL to a callback function. * * @param string $pattern URL pattern to match - * @param callback $callback Callback function + * @param callable $callback Callback function * @param bool $pass_route Pass the matching route object to the callback */ public function _put(string $pattern, callable $callback, bool $pass_route = false): void @@ -473,7 +478,7 @@ class Engine * Routes a URL to a callback function. * * @param string $pattern URL pattern to match - * @param callback $callback Callback function + * @param callable $callback Callback function * @param bool $pass_route Pass the matching route object to the callback */ public function _patch(string $pattern, callable $callback, bool $pass_route = false): void @@ -485,7 +490,7 @@ class Engine * Routes a URL to a callback function. * * @param string $pattern URL pattern to match - * @param callback $callback Callback function + * @param callable $callback Callback function * @param bool $pass_route Pass the matching route object to the callback */ public function _delete(string $pattern, callable $callback, bool $pass_route = false): void @@ -555,7 +560,7 @@ class Engine * Renders a template. * * @param string $file Template file - * @param array|null $data Template data + * @param ?array $data Template data * @param string|null $key View variable name * * @throws Exception diff --git a/flight/Flight.php b/flight/Flight.php index 101c455..2bca787 100644 --- a/flight/Flight.php +++ b/flight/Flight.php @@ -18,36 +18,27 @@ use flight\template\View; /** * The Flight class is a static representation of the framework. * - * Core. - * * @method static void start() Starts the framework. - * @method static void path($path) Adds a path for autoloading classes. + * @method static void path(string $path) Adds a path for autoloading classes. * @method static void stop() Stops the framework and sends a response. - * @method static void halt($code = 200, $message = '') Stop the framework with an optional status code and message. + * @method static void halt(int $code = 200, string $message = '') Stop the framework with an optional status code and message. * - * Routing. - * @method static void route($pattern, $callback) Maps a URL pattern to a callback. + * @method static void route(string $pattern, callable $callback) Maps a URL pattern to a callback. * @method static Router router() Returns Router instance. * - * Extending & Overriding. - * @method static void map($name, $callback) Creates a custom framework method. - * @method static void register($name, $class, array $params = array(), $callback = null) Registers a class to a framework method. + * @method static void map(string $name, callable $callback) Creates a custom framework method. * - * Filtering. * @method static void before($name, $callback) Adds a filter before a framework method. * @method static void after($name, $callback) Adds a filter after a framework method. * - * Variables. * @method static void set($key, $value) Sets a variable. * @method static mixed get($key) Gets a variable. * @method static bool has($key) Checks if a variable is set. * @method static void clear($key = null) Clears a variable. * - * Views. * @method static void render($file, array $data = null, $key = null) Renders a template file. * @method static View view() Returns View instance. * - * Request & Response. * @method static Request request() Returns Request instance. * @method static Response response() Returns Response instance. * @method static void redirect($url, $code = 303) Redirects to another URL. @@ -56,7 +47,6 @@ use flight\template\View; * @method static void error($exception) Sends an HTTP 500 response. * @method static void notFound() Sends an HTTP 404 response. * - * HTTP Caching. * @method static void etag($id, $type = 'strong') Performs ETag HTTP caching. * @method static void lastModified($time) Performs last modified HTTP caching. */ @@ -72,19 +62,33 @@ class Flight { } - private function __destruct() + private function __clone() { } - private function __clone() - { + /** + * Registers a class to a framework method. + * @template T of object + * @param string $name Static method name + * ``` + * Flight::register('user', User::class); + * + * Flight::user(); # <- Return a User instance + * ``` + * @param class-string $class Fully Qualified Class Name + * @param array $params Class constructor params + * @param ?Closure(T $instance): void $callback Perform actions with the instance + * @return void + */ + static function register($name, $class, $params = array(), $callback = null) { + static::__callStatic('register', func_get_args()); } /** * Handles calls to static methods. * * @param string $name Method name - * @param array $params Method parameters + * @param array $params Method parameters * * @throws Exception * diff --git a/flight/core/Dispatcher.php b/flight/core/Dispatcher.php index 50b73f0..0f810bd 100644 --- a/flight/core/Dispatcher.php +++ b/flight/core/Dispatcher.php @@ -23,11 +23,13 @@ class Dispatcher { /** * Mapped events. + * @var array */ protected array $events = []; /** * Method filters. + * @var array>> */ protected array $filters = []; @@ -35,9 +37,9 @@ class Dispatcher * Dispatches an event. * * @param string $name Event name - * @param array $params Callback parameters + * @param array $params Callback parameters * - *@throws Exception + * @throws Exception * * @return mixed|null Output of callback */ @@ -65,7 +67,7 @@ class Dispatcher * Assigns a callback to an event. * * @param string $name Event name - * @param callback $callback Callback function + * @param callable $callback Callback function */ final public function set(string $name, callable $callback): void { @@ -77,7 +79,7 @@ class Dispatcher * * @param string $name Event name * - * @return callback $callback Callback function + * @return callable $callback Callback function */ final public function get(string $name): ?callable { @@ -118,7 +120,7 @@ class Dispatcher * * @param string $name Event name * @param string $type Filter type - * @param callback $callback Callback function + * @param callable $callback Callback function */ final public function hook(string $name, string $type, callable $callback): void { @@ -128,8 +130,8 @@ class Dispatcher /** * Executes a chain of method filters. * - * @param array $filters Chain of filters - * @param array $params Method parameters + * @param array $filters Chain of filters + * @param array $params Method parameters * @param mixed $output Method output * * @throws Exception @@ -148,10 +150,10 @@ class Dispatcher /** * Executes a callback function. * - * @param array|callback $callback Callback function - * @param array $params Function parameters + * @param callable|array $callback Callback function + * @param array $params Function parameters * - *@throws Exception + * @throws Exception * * @return mixed Function results */ @@ -170,7 +172,7 @@ class Dispatcher * Calls a function. * * @param callable|string $func Name of function to call - * @param array $params Function parameters + * @param array $params Function parameters * * @return mixed Function results */ @@ -203,7 +205,7 @@ class Dispatcher * Invokes a method. * * @param mixed $func Class method - * @param array $params Class method parameters + * @param array $params Class method parameters * * @return mixed Function results */ diff --git a/flight/core/Loader.php b/flight/core/Loader.php index 95874a6..5ff66fe 100644 --- a/flight/core/Loader.php +++ b/flight/core/Loader.php @@ -10,6 +10,7 @@ declare(strict_types=1); namespace flight\core; +use Closure; use Exception; use ReflectionClass; use ReflectionException; @@ -24,26 +25,30 @@ class Loader { /** * Registered classes. + * @var array, ?callable}> $classes */ protected array $classes = []; /** * Class instances. + * @var array */ protected array $instances = []; /** * Autoload directories. + * @var array */ protected static array $dirs = []; /** * Registers a class. + * @template T of object * * @param string $name Registry name - * @param callable|string $class Class name or function to instantiate class - * @param array $params Class initialization parameters - * @param callable|null $callback $callback Function to call after object instantiation + * @param class-string $class Class name or function to instantiate class + * @param array $params Class initialization parameters + * @param ?callable(T $instance): void $callback $callback Function to call after object instantiation */ public function register(string $name, $class, array $params = [], ?callable $callback = null): void { @@ -77,7 +82,7 @@ class Loader $obj = null; if (isset($this->classes[$name])) { - [$class, $params, $callback] = $this->classes[$name]; + [0 => $class, 1 => $params, 2 => $callback] = $this->classes[$name]; $exists = isset($this->instances[$name]); @@ -116,15 +121,16 @@ class Loader /** * Gets a new instance of a class. + * @template T of object * - * @param callable|string $class Class name or callback function to instantiate class - * @param array $params Class initialization parameters + * @param class-string|Closure(): class-string $class Class name or callback function to instantiate class + * @param array $params Class initialization parameters * * @throws Exception * - * @return object Class instance + * @return T Class instance */ - public function newInstance($class, array $params = []): object + public function newInstance($class, array $params = []) { if (\is_callable($class)) { return \call_user_func_array($class, $params); @@ -179,7 +185,7 @@ class Loader * Starts/stops autoloader. * * @param bool $enabled Enable/disable autoloading - * @param mixed $dirs Autoload directories + * @param string|iterable $dirs Autoload directories */ public static function autoload(bool $enabled = true, $dirs = []): void { @@ -216,7 +222,7 @@ class Loader /** * Adds a directory for autoloading classes. * - * @param mixed $dir Directory path + * @param string|iterable $dir Directory path */ public static function addDirectory($dir): void { diff --git a/flight/net/Request.php b/flight/net/Request.php index 75d4665..8f8ecf8 100644 --- a/flight/net/Request.php +++ b/flight/net/Request.php @@ -18,23 +18,24 @@ use flight\util\Collection; * are stored and accessible via the Request object. * * The default request properties are: - * url - The URL being requested - * base - The parent subdirectory of the URL - * method - The request method (GET, POST, PUT, DELETE) - * referrer - The referrer URL - * ip - IP address of the client - * ajax - Whether the request is an AJAX request - * scheme - The server protocol (http, https) - * user_agent - Browser information - * type - The content type - * length - The content length - * query - Query string parameters - * data - Post parameters - * cookies - Cookie parameters - * files - Uploaded files - * secure - Connection is secure - * accept - HTTP accept parameters - * proxy_ip - Proxy IP address of the client + * + * - **url** - The URL being requested + * - **base** - The parent subdirectory of the URL + * - **method** - The request method (GET, POST, PUT, DELETE) + * - **referrer** - The referrer URL + * - **ip** - IP address of the client + * - **ajax** - Whether the request is an AJAX request + * - **scheme** - The server protocol (http, https) + * - **user_agent** - Browser information + * - **type** - The content type + * - **length** - The content length + * - **query** - Query string parameters + * - **data** - Post parameters + * - **cookies** - Cookie parameters + * - **files** - Uploaded files + * - **secure** - Connection is secure + * - **accept** - HTTP accept parameters + * - **proxy_ip** - Proxy IP address of the client */ final class Request { @@ -131,9 +132,9 @@ final class Request /** * Constructor. * - * @param array $config Request configuration + * @param array $config Request configuration */ - public function __construct(array $config = []) + public function __construct($config = array()) { // Default properties if (empty($config)) { @@ -165,7 +166,8 @@ final class Request /** * Initialize request properties. * - * @param array $properties Array of request properties + * @param array $properties Array of request properties + * @return static */ public function init(array $properties = []) { @@ -199,6 +201,8 @@ final class Request } } } + + return $this; } /** @@ -287,11 +291,11 @@ final class Request * * @param string $url URL string * - * @return array Query parameters + * @return array> */ public static function parseQuery(string $url): array { - $params = []; + $params = array(); $args = parse_url($url); if (isset($args['query'])) { diff --git a/flight/net/Response.php b/flight/net/Response.php index e21fc9a..5873ec7 100644 --- a/flight/net/Response.php +++ b/flight/net/Response.php @@ -25,7 +25,7 @@ class Response public bool $content_length = true; /** - * @var array HTTP status codes + * @var array HTTP status codes */ public static array $codes = [ 100 => 'Continue', @@ -103,7 +103,7 @@ class Response protected int $status = 200; /** - * @var array HTTP headers + * @var array> HTTP headers */ protected array $headers = []; @@ -124,7 +124,7 @@ class Response * * @throws Exception If invalid status code * - * @return int|object Self reference + * @return int|static Self reference */ public function status(?int $code = null) { @@ -144,10 +144,10 @@ class Response /** * Adds a header to the response. * - * @param array|string $name Header name or array of names and values + * @param array|string $name Header name or array of names and values * @param string|null $value Header value * - * @return object Self reference + * @return static Self reference */ public function header($name, ?string $value = null) { @@ -164,8 +164,7 @@ class Response /** * Returns the headers from the response. - * - * @return array + * @return array> */ public function headers() { @@ -203,7 +202,7 @@ class Response /** * Sets caching headers for the response. * - * @param int|string $expires Expiration time + * @param int|string|false $expires Expiration time * * @return Response Self reference */ diff --git a/flight/net/Route.php b/flight/net/Route.php index 91a6aff..fbfc20b 100644 --- a/flight/net/Route.php +++ b/flight/net/Route.php @@ -28,12 +28,12 @@ final class Route public $callback; /** - * @var array HTTP methods + * @var array HTTP methods */ public array $methods = []; /** - * @var array Route parameters + * @var array Route parameters */ public array $params = []; @@ -56,8 +56,8 @@ final class Route * Constructor. * * @param string $pattern URL pattern - * @param mixed $callback Callback function - * @param array $methods HTTP methods + * @param callable $callback Callback function + * @param array $methods HTTP methods * @param bool $pass Pass self in callback parameters */ public function __construct(string $pattern, $callback, array $methods, bool $pass) diff --git a/flight/net/Router.php b/flight/net/Router.php index dcf1591..f1f8842 100644 --- a/flight/net/Router.php +++ b/flight/net/Router.php @@ -23,6 +23,7 @@ class Router public bool $case_sensitive = false; /** * Mapped routes. + * @var array */ protected array $routes = []; @@ -34,7 +35,7 @@ class Router /** * Gets mapped routes. * - * @return array Array of routes + * @return array Array of routes */ public function getRoutes(): array { @@ -53,7 +54,7 @@ class Router * Maps a URL pattern to a callback function. * * @param string $pattern URL pattern to match - * @param callback $callback Callback function + * @param callable $callback Callback function * @param bool $pass_route Pass the matching route object to the callback */ public function map(string $pattern, callable $callback, bool $pass_route = false): void @@ -81,7 +82,7 @@ class Router { $url_decoded = urldecode($request->url); while ($route = $this->current()) { - if (false !== $route && $route->matchMethod($request->method) && $route->matchUrl($url_decoded, $this->case_sensitive)) { + if ($route->matchMethod($request->method) && $route->matchUrl($url_decoded, $this->case_sensitive)) { return $route; } $this->next(); diff --git a/flight/template/View.php b/flight/template/View.php index 90dbb81..f4d866c 100644 --- a/flight/template/View.php +++ b/flight/template/View.php @@ -34,7 +34,7 @@ class View /** * View variables. * - * @var array + * @var array */ protected $vars = []; @@ -70,8 +70,9 @@ class View /** * Sets a template variable. * - * @param mixed $key Key - * @param string $value Value + * @param string|iterable $key Key + * @param mixed $value Value + * @return static */ public function set($key, $value = null) { @@ -82,6 +83,8 @@ class View } else { $this->vars[$key] = $value; } + + return $this; } /** @@ -100,6 +103,7 @@ class View * Unsets a template variable. If no key is passed in, clear all variables. * * @param string $key Key + * @return static */ public function clear($key = null) { @@ -108,15 +112,18 @@ class View } else { unset($this->vars[$key]); } + + return $this; } /** * Renders a template. * * @param string $file Template file - * @param array $data Template data + * @param array $data Template data * * @throws \Exception If template not found + * @return void */ public function render($file, $data = null) { @@ -139,7 +146,7 @@ class View * Gets the output of a template. * * @param string $file Template file - * @param array $data Template data + * @param array $data Template data * * @return string Output of template */ @@ -196,5 +203,6 @@ class View public function e($str) { echo htmlentities($str); + return htmlentities($str); } } diff --git a/flight/util/Collection.php b/flight/util/Collection.php index 97658ec..5998b25 100644 --- a/flight/util/Collection.php +++ b/flight/util/Collection.php @@ -11,7 +11,6 @@ declare(strict_types=1); namespace flight\util; use ArrayAccess; -use function count; use Countable; use Iterator; use JsonSerializable; @@ -23,18 +22,21 @@ if (!interface_exists('JsonSerializable')) { /** * The Collection class allows you to access a set of data * using both array and object notation. + * @implements ArrayAccess + * @implements Iterator */ final class Collection implements ArrayAccess, Iterator, Countable, JsonSerializable { /** * Collection data. + * @var array */ private array $data; /** * Constructor. * - * @param array $data Initial data + * @param array $data Initial data */ public function __construct(array $data = []) { @@ -102,11 +104,11 @@ final class Collection implements ArrayAccess, Iterator, Countable, JsonSerializ /** * Sets an item at the offset. * - * @param string $offset Offset + * @param ?string $offset Offset * @param mixed $value Value */ #[\ReturnTypeWillChange] - public function offsetSet($offset, $value) + public function offsetSet($offset, $value): void { if (null === $offset) { $this->data[] = $value; @@ -169,13 +171,11 @@ final class Collection implements ArrayAccess, Iterator, Countable, JsonSerializ /** * Gets the next collection value. - * - * @return mixed Value */ #[\ReturnTypeWillChange] - public function next() + public function next(): void { - return next($this->data); + next($this->data); } /** @@ -187,7 +187,7 @@ final class Collection implements ArrayAccess, Iterator, Countable, JsonSerializ { $key = key($this->data); - return null !== $key && false !== $key; + return null !== $key; } /** @@ -203,7 +203,7 @@ final class Collection implements ArrayAccess, Iterator, Countable, JsonSerializ /** * Gets the item keys. * - * @return array Collection keys + * @return array Collection keys */ public function keys(): array { @@ -213,7 +213,7 @@ final class Collection implements ArrayAccess, Iterator, Countable, JsonSerializ /** * Gets the collection data. * - * @return array Collection data + * @return array Collection data */ public function getData(): array { @@ -223,19 +223,15 @@ final class Collection implements ArrayAccess, Iterator, Countable, JsonSerializ /** * Sets the collection data. * - * @param array $data New collection data + * @param array $data New collection data */ public function setData(array $data): void { $this->data = $data; } - /** - * Gets the collection data which can be serialized to JSON. - * - * @return array Collection data which can be serialized by json_encode - */ - public function jsonSerialize(): array + #[\ReturnTypeWillChange] + public function jsonSerialize() { return $this->data; } diff --git a/flight/util/LegacyJsonSerializable.php b/flight/util/LegacyJsonSerializable.php index 0c973aa..39e1721 100644 --- a/flight/util/LegacyJsonSerializable.php +++ b/flight/util/LegacyJsonSerializable.php @@ -9,5 +9,9 @@ declare(strict_types=1); */ interface LegacyJsonSerializable { + /** + * Gets the collection data which can be serialized to JSON. + * @return mixed Collection data which can be serialized by json_encode + */ public function jsonSerialize(); }