mirrors
/
flight-core
mirror of https://github.com/flightphp/core
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improved docblocks

Browse Source
pull/538/head
fadrian06 12 months ago
parent 097dd968b1
commit aeb8911038
7 changed files with 124 additions and 121 deletions
Show Stats Download Patch File Download Diff File

1
flight.sublime-project
Unescape View File

@ -6,6 +6,7 @@
} }
], ],
"settings": { "settings": {
"SublimeLinter.linters.phpstan.executable": "${project_path}/vendor/bin/phpstan.bat",
"LSP": { "LSP": {
"LSP-intelephense": { "LSP-intelephense": {
"settings": { "settings": {

113
flight/Engine.php
Unescape View File

@ -63,7 +63,6 @@ use flight\net\Route;
* @method void etag($id, string $type = 'strong') Handles ETag HTTP caching. * @method void etag($id, string $type = 'strong') Handles ETag HTTP caching.
* @method void lastModified(int $time) Handles last modified HTTP caching. * @method void lastModified(int $time) Handles last modified HTTP caching.
*/ */
// phpcs:ignoreFile Generic.Files.LineLength.TooLong, PSR2.Methods.MethodDeclaration.Underscore
class Engine class Engine
{ {
/** /**
@ -243,13 +242,21 @@ class Engine
/** /**
* Registers a class to a framework method. * Registers a class to a framework method.
* @template T of object
* *
* @param string $name Method name * # Usage example:
* @param class-string<T> $class Class name * ```
* @param array<int, mixed> $params Class initialization parameters * $app = new Engine;
* @param ?callable(T $instance): void $callback Function to call after object instantiation * $app->register('user', User::class);
*
* $app->user(); # <- Return a User instance
* ```
*
* @param string $name Method name
* @param class-string<T> $class Class name
* @param array<int, mixed> $params Class initialization parameters
* @param ?Closure(T $instance): void $callback Function to call after object instantiation
* *
* @template T of object
* @throws Exception If trying to map over a framework method * @throws Exception If trying to map over a framework method
*/ */
public function register(string $name, string $class, array $params = [], ?callable $callback = null): void public function register(string $name, string $class, array $params = [], ?callable $callback = null): void
@ -270,8 +277,8 @@ class Engine
/** /**
* Adds a pre-filter to a method. * Adds a pre-filter to a method.
* *
* @param string $name Method name * @param string $name Method name
* @param callable $callback Callback function * @param Closure(array<int, mixed> &$params, string &$output): (void|false) $callback
*/ */
public function before(string $name, callable $callback): void public function before(string $name, callable $callback): void
{ {
@ -281,8 +288,8 @@ class Engine
/** /**
* Adds a post-filter to a method. * Adds a post-filter to a method.
* *
* @param string $name Method name * @param string $name Method name
* @param callable $callback Callback function * @param Closure(array<int, mixed> &$params, string &$output): (void|false) $callback
*/ */
public function after(string $name, callable $callback): void public function after(string $name, callable $callback): void
{ {
@ -292,9 +299,9 @@ class Engine
/** /**
* Gets a variable. * Gets a variable.
* *
* @param string|null $key Key * @param ?string $key Variable name
* *
* @return array|mixed|null * @return mixed Variable value or `null` if `$key` doesn't exists.
*/ */
public function get(?string $key = null) public function get(?string $key = null)
{ {
@ -308,24 +315,27 @@ class Engine
/** /**
* Sets a variable. * Sets a variable.
* *
* @param mixed $key Key * @param string|iterable<string, mixed> $key
* @param mixed|null $value Value * Variable name as `string` or an iterable of `'varName' => $varValue`
* @param mixed $value Ignored if `$key` is an `iterable`
*/ */
public function set($key, $value = null): void public function set($key, $value = null): void
{ {
if (\is_array($key) || \is_object($key)) { if (\is_iterable($key)) {
foreach ($key as $k => $v) { foreach ($key as $k => $v) {
$this->vars[$k] = $v; $this->vars[$k] = $v;
} }
} else {
$this->vars[$key] = $value; return;
} }
$this->vars[$key] = $value;
} }
/** /**
* Checks if a variable has been set. * Checks if a variable has been set.
* *
* @param string $key Key * @param string $key Variable name
* *
* @return bool Variable status * @return bool Variable status
*/ */
@ -337,15 +347,16 @@ class Engine
/** /**
* Unsets a variable. If no key is passed in, clear all variables. * Unsets a variable. If no key is passed in, clear all variables.
* *
* @param string|null $key Key * @param ?string $key Variable name, if `$key` isn't provided, it clear all variables.
*/ */
public function clear(?string $key = null): void public function clear(?string $key = null): void
{ {
if (null === $key) { if (null === $key) {
$this->vars = []; $this->vars = [];
} else { return;
unset($this->vars[$key]);
} }
unset($this->vars[$key]);
} }
/** /**
@ -478,7 +489,7 @@ class Engine
* *
* @param Throwable $e Thrown exception * @param Throwable $e Thrown exception
*/ */
public function _error($e): void public function _error(Throwable $e): void
{ {
$msg = sprintf( $msg = sprintf(
'<h1>500 Internal Server Error</h1>' . '<h1>500 Internal Server Error</h1>' .
@ -505,7 +516,7 @@ class Engine
/** /**
* Stops the framework and outputs the current response. * Stops the framework and outputs the current response.
* *
* @param int|null $code HTTP status code * @param ?int $code HTTP status code
* *
* @throws Exception * @throws Exception
*/ */
@ -558,9 +569,9 @@ class Engine
* @param callable $callback Callback function * @param callable $callback Callback function
* @param bool $pass_route Pass the matching route object to the callback * @param bool $pass_route Pass the matching route object to the callback
*/ */
public function _post(string $pattern, callable $callback, bool $pass_route = false): void public function _post(string $pattern, callable $callback, bool $pass_route = false, string $route_alias = ''): void
{ {
$this->router()->map('POST ' . $pattern, $callback, $pass_route); $this->router()->map('POST ' . $pattern, $callback, $pass_route, $route_alias);
} }
/** /**
@ -570,9 +581,9 @@ class Engine
* @param callable $callback Callback function * @param callable $callback Callback function
* @param bool $pass_route Pass the matching route object to the callback * @param bool $pass_route Pass the matching route object to the callback
*/ */
public function _put(string $pattern, callable $callback, bool $pass_route = false): void public function _put(string $pattern, callable $callback, bool $pass_route = false, string $route_alias = ''): void
{ {
$this->router()->map('PUT ' . $pattern, $callback, $pass_route); $this->router()->map('PUT ' . $pattern, $callback, $pass_route, $route_alias);
} }
/** /**
@ -582,9 +593,9 @@ class Engine
* @param callable $callback Callback function * @param callable $callback Callback function
* @param bool $pass_route Pass the matching route object to the callback * @param bool $pass_route Pass the matching route object to the callback
*/ */
public function _patch(string $pattern, callable $callback, bool $pass_route = false): void public function _patch(string $pattern, callable $callback, bool $pass_route = false, string $route_alias = ''): void
{ {
$this->router()->map('PATCH ' . $pattern, $callback, $pass_route); $this->router()->map('PATCH ' . $pattern, $callback, $pass_route, $route_alias);
} }
/** /**
@ -594,9 +605,9 @@ class Engine
* @param callable $callback Callback function * @param callable $callback Callback function
* @param bool $pass_route Pass the matching route object to the callback * @param bool $pass_route Pass the matching route object to the callback
*/ */
public function _delete(string $pattern, callable $callback, bool $pass_route = false): void public function _delete(string $pattern, callable $callback, bool $pass_route = false, string $route_alias = ''): void
{ {
$this->router()->map('DELETE ' . $pattern, $callback, $pass_route); $this->router()->map('DELETE ' . $pattern, $callback, $pass_route, $route_alias);
} }
/** /**
@ -618,9 +629,7 @@ class Engine
} }
} }
/** /** Sends an HTTP 404 response when a URL is not found. */
* Sends an HTTP 404 response when a URL is not found.
*/
public function _notFound(): void public function _notFound(): void
{ {
$this->response() $this->response()
@ -637,7 +646,7 @@ class Engine
* Redirects the current request to another URL. * Redirects the current request to another URL.
* *
* @param string $url URL * @param string $url URL
* @param int $code HTTP status code * @param int $code HTTP status code
*/ */
public function _redirect(string $url, int $code = 303): void public function _redirect(string $url, int $code = 303): void
{ {
@ -662,29 +671,30 @@ class Engine
/** /**
* Renders a template. * Renders a template.
* *
* @param string $file Template file * @param string $file Template file
* @param ?array<string, mixed> $data Template data * @param ?array<string, mixed> $data Template data
* @param string|null $key View variable name * @param ?string $key View variable name
* *
* @throws Exception * @throws Exception If template file wasn't found
*/ */
public function _render(string $file, ?array $data = null, ?string $key = null): void public function _render(string $file, ?array $data = null, ?string $key = null): void
{ {
if (null !== $key) { if (null !== $key) {
$this->view()->set($key, $this->view()->fetch($file, $data)); $this->view()->set($key, $this->view()->fetch($file, $data));
} else { return;
$this->view()->render($file, $data);
} }
$this->view()->render($file, $data);
} }
/** /**
* Sends a JSON response. * Sends a JSON response.
* *
* @param mixed $data JSON data * @param mixed $data JSON data
* @param int $code HTTP status code * @param int $code HTTP status code
* @param bool $encode Whether to perform JSON encoding * @param bool $encode Whether to perform JSON encoding
* @param string $charset Charset * @param string $charset Charset
* @param int $option Bitmask Json constant such as JSON_HEX_QUOT * @param int $option Bitmask Json constant such as JSON_HEX_QUOT
* *
* @throws Exception * @throws Exception
*/ */
@ -707,12 +717,12 @@ class Engine
/** /**
* Sends a JSONP response. * Sends a JSONP response.
* *
* @param mixed $data JSON data * @param mixed $data JSON data
* @param string $param Query parameter that specifies the callback name. * @param string $param Query parameter that specifies the callback name.
* @param int $code HTTP status code * @param int $code HTTP status code
* @param bool $encode Whether to perform JSON encoding * @param bool $encode Whether to perform JSON encoding
* @param string $charset Charset * @param string $charset Charset
* @param int $option Bitmask Json constant such as JSON_HEX_QUOT * @param int $option Bitmask Json constant such as JSON_HEX_QUOT
* *
* @throws Exception * @throws Exception
*/ */
@ -725,7 +735,6 @@ class Engine
int $option = 0 int $option = 0
): void { ): void {
$json = $encode ? json_encode($data, $option) : $data; $json = $encode ? json_encode($data, $option) : $data;
$callback = $this->request()->query[$param]; $callback = $this->request()->query[$param];
$this->response() $this->response()
@ -738,8 +747,8 @@ class Engine
/** /**
* Handles ETag HTTP caching. * Handles ETag HTTP caching.
* *
* @param string $id ETag identifier * @param string $id ETag identifier
* @param string $type ETag type * @param 'strong'|'weak' $type ETag type
*/ */
public function _etag(string $id, string $type = 'strong'): void public function _etag(string $id, string $type = 'strong'): void
{ {

112
flight/Flight.php
Unescape View File

@ -12,74 +12,71 @@ use flight\net\Route;
/** /**
* The Flight class is a static representation of the framework. * The Flight class is a static representation of the framework.
*
* @license MIT, http://flightphp.com/license * @license MIT, http://flightphp.com/license
* @copyright Copyright (c) 2011, Mike Cao <mike@mikecao.com> * @copyright Copyright (c) 2011, Mike Cao <mike@mikecao.com>
* *
* # Core methods * # Core methods
* @method static void start() Starts the framework. * @method static void start() Starts the framework.
* @method static void path(string $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 stop(?int $code = null) Stops the framework and sends a response.
* @method static void halt(int $code = 200, string $message = '') * @method static void halt(int $code = 200, string $message = '')
* Stop the framework with an optional status code and message. * Stop the framework with an optional status code and message.
* *
* # Routing * # Routing
* @method static Route route(string $pattern, callable $callback, bool $pass_route = false, string $alias = '') * @method static Route route(string $pattern, callable $callback, bool $pass_route = false, string $alias = '')
* Maps a URL pattern to a callback with all applicable methods. * Maps a URL pattern to a callback with all applicable methods.
* @method static void group(string $pattern, callable $callback, array $group_middlewares = []) * @method static void group(string $pattern, callable $callback, callable[] $group_middlewares = [])
* Groups a set of routes together under a common prefix. * Groups a set of routes together under a common prefix.
* @method static Route post(string $pattern, callable $callback, bool $pass_route = false, string $alias = '') * @method static Route post(string $pattern, callable $callback, bool $pass_route = false, string $alias = '')
* Routes a POST URL to a callback function. * Routes a POST URL to a callback function.
* @method static Route put(string $pattern, callable $callback, bool $pass_route = false, string $alias = '') * @method static Route put(string $pattern, callable $callback, bool $pass_route = false, string $alias = '')
* Routes a PUT URL to a callback function. * Routes a PUT URL to a callback function.
* @method static Route patch(string $pattern, callable $callback, bool $pass_route = false, string $alias = '') * @method static Route patch(string $pattern, callable $callback, bool $pass_route = false, string $alias = '')
* Routes a PATCH URL to a callback function. * Routes a PATCH URL to a callback function.
* @method static Route delete(string $pattern, callable $callback, bool $pass_route = false, string $alias = '') * @method static Route delete(string $pattern, callable $callback, bool $pass_route = false, string $alias = '')
* Routes a DELETE URL to a callback function. * Routes a DELETE URL to a callback function.
* @method static Router router() Returns Router instance. * @method static Router router() Returns Router instance.
* @method static string getUrl(string $alias) Gets a url from an alias * @method static string getUrl(string $alias, array<string, mixed> $params = []) Gets a url from an alias
* *
* @method static void map(string $name, callable $callback) Creates a custom framework method. * @method static void map(string $name, callable $callback) Creates a custom framework method.
* *
* @method static void before($name, $callback) Adds a filter before a framework method. * @method static void before(string $name, Closure(array<int, mixed> &$params, string &$output): (void|false) $callback)
* @method static void after($name, $callback) Adds a filter after a framework method. * Adds a filter before a framework method.
* @method static void after(string $name, Closure(array<int, mixed> &$params, string &$output): (void|false) $callback)
* Adds a filter after a framework method.
* *
* @method static void set($key, $value) Sets a variable. * @method static void set(string|iterable<string, mixed> $key, mixed $value) Sets a variable.
* @method static mixed get($key) Gets a variable. * @method static mixed get(?string $key) Gets a variable.
* @method static bool has($key) Checks if a variable is set. * @method static bool has(string $key) Checks if a variable is set.
* @method static void clear($key = null) Clears a variable. * @method static void clear(?string $key = null) Clears a variable.
* *
* # Views * # Views
* @method static void render($file, array $data = null, $key = null) Renders a template file. * @method static void render(string $file, ?array<string, mixed> $data = null, ?string $key = null)
* @method static View view() Returns View instance. * Renders a template file.
* @method static View view() Returns View instance.
* *
* # Request-Response * # Request-Response
* @method static Request request() Returns Request instance. * @method static Request request() Returns Request instance.
* @method static Response response() Returns Response instance. * @method static Response response() Returns Response instance.
* @method static void redirect($url, $code = 303) Redirects to another URL. * @method static void redirect(string $url, int $code = 303) Redirects to another URL.
* @method static void json($data, $code = 200, $encode = true, $charset = "utf8", $encodeOption = 0, $encodeDepth = 512) Sends a JSON response. * @method static void json(mixed $data, int $code = 200, bool $encode = true, string $charset = "utf8", int $encodeOption = 0, int $encodeDepth = 512)
* @method static void jsonp($data, $param = 'jsonp', $code = 200, $encode = true, $charset = "utf8", $encodeOption = 0, $encodeDepth = 512) Sends a JSONP response. * Sends a JSON response.
* @method static void error($exception) Sends an HTTP 500 response. * @method static void jsonp(mixed $data, string $param = 'jsonp', int $code = 200, bool $encode = true, string $charset = "utf8", int $encodeOption = 0, int $encodeDepth = 512)
* @method static void notFound() Sends an HTTP 404 response. * Sends a JSONP response.
* @method static void error(Throwable $exception) Sends an HTTP 500 response.
* @method static void notFound() Sends an HTTP 404 response.
* *
* # HTTP caching * # HTTP caching
* @method static void etag($id, $type = 'strong') Performs ETag HTTP caching. * @method static void etag(string $id, 'strong'|'weak' $type = 'strong') Performs ETag HTTP caching.
* @method static void lastModified($time) Performs last modified HTTP caching. * @method static void lastModified(int $time) Performs last modified HTTP caching.
*/ */
// phpcs:ignoreFile Generic.Files.LineLength.TooLong, PSR1.Classes.ClassDeclaration.MissingNamespace class Flight
class Flight
{ {
/** /** Framework engine. */
* Framework engine.
*
* @var Engine $engine
*/
private static Engine $engine; private static Engine $engine;
/** /** Whether or not the app has been initialized. */
* Whether or not the app has been initialized
*
* @var boolean
*/
private static bool $initialized = false; private static bool $initialized = false;
/** /**
@ -104,56 +101,53 @@ class Flight
/** /**
* Registers a class to a framework method. * Registers a class to a framework method.
* @template T of object *
* @param string $name Static method name * # Usage example:
* ``` * ```
* Flight::register('user', User::class); * Flight::register('user', User::class);
* *
* Flight::user(); # <- Return a User instance * Flight::user(); # <- Return a User instance
* ``` * ```
* @param class-string<T> $class Fully Qualified Class Name *
* @param array<int, mixed> $params Class constructor params * @param string $name Static method name
* @param ?Closure(T $instance): void $callback Perform actions with the instance * @param class-string<T> $class Fully Qualified Class Name
* @return void * @param array<int, mixed> $params Class constructor params
* @param ?Closure(T $instance): void $callback Perform actions with the instance
*
* @template T of object
*/ */
public static function register($name, $class, $params = [], $callback = null) public static function register($name, $class, $params = [], $callback = null): void
{ {
static::__callStatic('register', func_get_args()); static::__callStatic('register', [$name, $class, $params, $callback]);
} }
/** Unregisters a class. */ /** Unregisters a class. */
public static function unregister(string $methodName): void public static function unregister(string $methodName): void
{ {
static::__callStatic('unregister', func_get_args()); static::__callStatic('unregister', [$methodName]);
} }
/** /**
* Handles calls to static methods. * Handles calls to static methods.
* *
* @param string $name Method name * @param string $name Method name
* @param array<int, mixed> $params Method parameters * @param array<int, mixed> $params Method parameters
*
* @throws Exception
* *
* @return mixed Callback results * @return mixed Callback results
* @throws Exception
*/ */
public static function __callStatic(string $name, array $params) public static function __callStatic(string $name, array $params)
{ {
$app = self::app(); return Dispatcher::invokeMethod([self::app(), $name], $params);
return Dispatcher::invokeMethod([$app, $name], $params);
} }
/** /** @return Engine Application instance */
* @return Engine Application instance
*/
public static function app(): Engine public static function app(): Engine
{ {
if (!self::$initialized) { if (!self::$initialized) {
require_once __DIR__ . '/autoload.php'; require_once __DIR__ . '/autoload.php';
self::setEngine(new Engine()); self::setEngine(new Engine());
self::$initialized = true; self::$initialized = true;
} }

7
flight/core/Dispatcher.php
Unescape View File

@ -4,6 +4,7 @@ declare(strict_types=1);
namespace flight\core; namespace flight\core;
use Closure;
use Exception; use Exception;
use InvalidArgumentException; use InvalidArgumentException;
@ -117,9 +118,9 @@ class Dispatcher
/** /**
* Hooks a callback to an event. * Hooks a callback to an event.
* *
* @param string $name Event name * @param string $name Event name
* @param string $type Filter type * @param 'before'|'after' $type Filter type
* @param callable $callback Callback function * @param Closure(array<int, mixed> &$params, string &$output): (void|false) $callback
*/ */
public function hook(string $name, string $type, callable $callback): void public function hook(string $name, string $type, callable $callback): void
{ {

10
flight/core/Loader.php
Unescape View File

@ -42,14 +42,12 @@ class Loader
/** /**
* Registers a class. * Registers a class.
* *
* @param string $name Registry name * @param string $name Registry name
* @param class-string<T>|Closure(): T $class Class name or function to instantiate class * @param class-string<T>|Closure(): T $class Class name or function to instantiate class
* @param array<int, mixed> $params Class initialization parameters * @param array<int, mixed> $params Class initialization parameters
* @param ?callable(T $instance): void $callback $callback Function to call after object instantiation * @param ?Closure(T $instance): void $callback $callback Function to call after object instantiation
* *
* @template T of object * @template T of object
*
* @return void
*/ */
public function register(string $name, $class, array $params = [], ?callable $callback = null): void public function register(string $name, $class, array $params = [], ?callable $callback = null): void
{ {

1
phpcs.xml
Unescape View File

@ -34,6 +34,7 @@
<exclude name="Generic.ControlStructures.DisallowYodaConditions.Found" /> <exclude name="Generic.ControlStructures.DisallowYodaConditions.Found" />
<exclude name="Generic.Strings.UnnecessaryStringConcat.Found" /> <exclude name="Generic.Strings.UnnecessaryStringConcat.Found" />
<exclude name="Generic.CodeAnalysis.AssignmentInCondition.FoundInWhileCondition" /> <exclude name="Generic.CodeAnalysis.AssignmentInCondition.FoundInWhileCondition" />
<exclude name="Generic.Commenting.DocComment.MissingShort" />
</rule> </rule>
<file>flight/</file> <file>flight/</file>
<file>tests/</file> <file>tests/</file>

1
tests/FlightTest.php
Unescape View File

@ -164,7 +164,6 @@ class FlightTest extends TestCase
public function testStaticRoutePut() public function testStaticRoutePut()
{ {
Flight::put('/test', function () { Flight::put('/test', function () {
echo 'test put'; echo 'test put';
}); });

Write Preview
Loading…
Cancel
Save