From 1146a809569ebd26b76f7569e343b2b4900a7293 Mon Sep 17 00:00:00 2001 From: Rodolfo Berrios <20590102+rodber@users.noreply.github.com> Date: Wed, 24 Jan 2024 15:09:13 -0300 Subject: [PATCH] wip --- developer/spec/exceptions.md | 41 ------- developer/spec/naming.php | 3 +- developer/standard/coding.md | 1 - developer/standard/quality.md | 3 +- introduction/README.md | 16 +-- introduction/installation.md | 28 +---- library/naming.php | 9 -- library/string.md | 105 ------------------ library/type.md | 77 ------------- {library => packages}/filesystem.md | 10 +- packages/naming.php | 1 + packages/sql2p.md | 2 +- {library => packages}/standard.md | 10 +- .../var-support.md | 14 ++- 14 files changed, 34 insertions(+), 286 deletions(-) delete mode 100644 developer/spec/exceptions.md delete mode 100644 library/naming.php delete mode 100644 library/string.md delete mode 100644 library/type.md rename {library => packages}/filesystem.md (95%) rename {library => packages}/standard.md (89%) rename library/variable-support.md => packages/var-support.md (76%) diff --git a/developer/spec/exceptions.md b/developer/spec/exceptions.md deleted file mode 100644 index 7f261b15..00000000 --- a/developer/spec/exceptions.md +++ /dev/null @@ -1,41 +0,0 @@ -# Exceptions Spec - -Exceptions are error events that happens on runtime, that disrupts the execution of the software. - -## Conventions - -Interfaces **must**: - -* Define a descriptive name -* Named with `Exception` suffix -* Extend `Chevere\Throwable\Exception` -* Located at `Chevere//Exceptions` namespace - -## Design - -### Uniqueness - -Each different error event **should** have its own unique exception. - -### Descriptive - -Use names that explain the context of the exception. For example, `SomeException` is less descriptive than `RoutingBadRouteException`. - -## Throwing Exceptions - -### Exception Message - -A [Message](../../library/message.md) **should** explain the error event when needed. - -Exception messages **must**: - -* Describe the error -* Indicate the conflict element - -Exception messages **should not**: - -* Provide *hints* in how-to deal with the error - -### Previous Exception - -Passing previous exception **should** be preferred and wrapping **should** be avoided. diff --git a/developer/spec/naming.php b/developer/spec/naming.php index f2a26909..66c4375a 100644 --- a/developer/spec/naming.php +++ b/developer/spec/naming.php @@ -3,5 +3,4 @@ return [ 'interfaces.md' => 'Interfaces', 'components.md' => 'Components', - 'exceptions.md' => 'Exceptions', -]; \ No newline at end of file +]; diff --git a/developer/standard/coding.md b/developer/standard/coding.md index 90d4196a..ecf72257 100644 --- a/developer/standard/coding.md +++ b/developer/standard/coding.md @@ -93,5 +93,4 @@ Comments in logic should be used only in the following cases: DocBlock content should be **short** as possible, **relevant** and **omit** the obvious. * Use markdown -* `@throws` must be provided for all known exceptions * `@param` and `@return` should be avoided (prefer typed code) diff --git a/developer/standard/quality.md b/developer/standard/quality.md index 14fc4804..d6b7fa91 100644 --- a/developer/standard/quality.md +++ b/developer/standard/quality.md @@ -19,7 +19,6 @@ We use the following third-party CI services: * [SonarCloud](https://sonarcloud.io/) * [CodeFactor](https://www.codefactor.io/) -* [Codacy](https://www.codacy.com/) * [Stryker Mutator](https://stryker-mutator.io/) ## Extensively tested @@ -32,7 +31,7 @@ To ensure the quality of the tests, all Chevere software requires **mutation tes All Chevere software **must** be documented. -We use [docs-deploy](https://github.com/chevere/docs-deploy), which is our own documenting system. +We use [docs-deploy](https://github.com/chevere/docs-deploy) documenting system. ## PHPStan Level 9 diff --git a/introduction/README.md b/introduction/README.md index 01167cd3..2eed95cd 100644 --- a/introduction/README.md +++ b/introduction/README.md @@ -2,7 +2,7 @@ ## What is Chevere? -Chevere is a strict, strong-typed PHP development library. It is the stuff developers use to build *other* software as it is an small software package providing the core tooling needed to organize and run the logic of any given software application. +Chevere is a strict, strong-typed PHP development library. It is the stuff developers use to build *other* software as it is a collection of packages providing the core tooling needed to organize and run the logic of any given software application. 💡 The term *chévere* is ubiquitous in Latin America, known in every Spanish speaking country and it means **cool/awesome**. @@ -10,27 +10,19 @@ Chevere is a strict, strong-typed PHP development library. It is the stuff devel ### Clean & Typed -Chevere follows [Clean Code](http://cleancoder.com/products) principles, which can be resumed as the practice of creating code that is easy to understand, to change and maintain. +Chevere follows Clean Code principles, which can be resumed as the practice of creating code that is easy to understand, to change and maintain. ### Extensible -A core library tooling for general purposes, with enough flexibility to allow the creation a myriad of systems with the same know-how. Also packages for specific needs. +Packages of all types, with enough flexibility to allow the creation a myriad of systems with the same know-how. ### Modern & High quality All-new PHP 8 codebase with strict standards. Chevere has been designed from scratch for PHP 8, and it uses all the goodies added to it. On top of that it follows own high [quality](../developer/standard/quality.md) standards. -## Why Chevere and not X? - -If you can use software from *well-known* vendors why you should use Chevere? - -Main reason for Chevere is its high quality with a clean syntax. You can tell that by interacting with Chevere and because the code is scrutinized by several third-party tools. - -It is day and night when the arguments to use a codebase are vague subjective terms like *expressive syntax* or *well-maintained* compared to objetive code measure metrics. - ## Who makes Chevere? -Chevere is driven by [Chevereto](https://chevereto.com) and is made by the same author ([Rodolfo Berrios](https://rodolfoberrios.com), hi) with solid 18+ years of experience building systems. +Chevere is driven by [Chevereto](https://chevereto.com) and is made by the same author ([Rodolfo Berrios](https://rodolfoberrios.com), hi). Chevere was created as the supporting framework for Chevereto, and Chevereto supports Chevere's development. diff --git a/introduction/installation.md b/introduction/installation.md index a8b009cd..00f6c8c4 100644 --- a/introduction/installation.md +++ b/introduction/installation.md @@ -1,33 +1,9 @@ # Installation -## System Requirements +Chevere is a set of [PHP packages](https://packagist.org/packages/chevere/) packages that can be installed using [Composer](https://getcomposer.org/). -💡 Chevere system requirements can be found in the `composer.json` file. - -### PHP - -Chevere is built and tested for [unix-like systems](../developer/environment/system.md#operating-system). - -* [PHP 8](https://www.php.net/releases/8.0) - -The [chevere.ini](https://github.com/chevere/chevere/blob/main/chevere.ini) file provides the PHP settings required for Chevere. - -## Installing - -* Requires [Composer](https://getcomposer.org/) +If you need to use several packages consider installing [chevere/chevere](https://github.com/chevere/chevere) which contains all packages. ```sh composer require chevere/chevere ``` - -The above command will install Chevere and its dependencies at `vendor/`. - -## Now what? - -Chevere will be available project-wide. Make sure to load `vendor/autoload.php` in your entry point: - -```php -require 'vendor/autoload.php'; -``` - -Once installed you can start using any of the built-in [components](../library/README.md). diff --git a/library/naming.php b/library/naming.php deleted file mode 100644 index 96d9a7a6..00000000 --- a/library/naming.php +++ /dev/null @@ -1,9 +0,0 @@ - 'Controller', - 'string.md' => 'String', - 'type.md' => 'Type', - 'variable-support.md' => 'VariableSupport', -]; diff --git a/library/string.md b/library/string.md deleted file mode 100644 index 0c4e4f16..00000000 --- a/library/string.md +++ /dev/null @@ -1,105 +0,0 @@ -# String - -Namespace `Chevere\String` - -The String component provides interaction with strings, allowing [manipulation](#manipulation), [asserting](#asserting) and [boolean checking](#boolean-checking) for variables of type `string`. - -## Modification - -The `ModifyString` component in charge of string modification. - -String modification refers to the process of altering an argument of type `string`. - -```php -use Chevere\String\ModifyString; - -$modify = (new ModifyString(' THE STRING ')) - ->lowercase() - ->stripWhitespace(); - -$string = $modify->__toString(); -// thestring -``` - -Table below contains all the methods available for string modification. - -| Methods | -| ------------------------- | -| withForwardSlashes | -| withLeftTail | -| withLowercase | -| withReplaceAll | -| withReplaceFirst | -| withReplaceLast | -| withRightTail | -| withStripANSIColors | -| withStripExtraWhitespace | -| withStripNonAlphanumerics | -| withStripWhitespace | -| withUppercase | - -## Asserting - -The `AssertString` component in charge of string asserting. - -Asserting strings refers to the process of asserting an argument of type `string` against methods that throws `Throwable` when failing to assert. - -```php -use new Chevere\Str\AssertString; - -// Throws Exception -(new AssertString('A String')) - ->notEmpty() - ->notCtypeSpace(); -``` - -In the code above, executing `notEmpty` won't raise any exception as `$string` is not an empty string, but executing `notCtypeSpace` will raise an exception as `$string` contains c-type spaces. - -Table below contains all the methods available for string assertion checking. - -| Methods | -| ----------------------- | -| contains | -| ctypeDigit | -| ctypeSpace | -| empty | -| endsWith | -| same | -| startsWith | -| startsWithCtypeDigit | -| notContains | -| notCtypeDigit | -| notCtypeSpace | -| notEmpty | -| notEndsWith | -| notSame | -| notStartsWith | -| notStartsWithCtypeDigit | - -## Boolean checking - -Bool string refers to the process of validating an argument of type `string` against methods that returns `bool`. - -The `ValidateString` component in charge of string validation. - -```php -use new Chevere\String\ValidateString; - -$string = 'Chévere es magnífico!'; -$validate = new ValidateString($string); -$false = $validate->endsWith('Rodo'); -$true = $validate->contains('es'); -$true = $validate->startsWith('Chévere'); -``` - -Table below contains all the methods available for string boolean checking. - -| Methods | -| ------------------------ | -| isCtypeDigit | -| isCtypeSpace | -| isEmpty | -| isEndingWith | -| isSame | -| isStartingWith | -| isStartingWithCtypeDigit | diff --git a/library/type.md b/library/type.md deleted file mode 100644 index c7499182..00000000 --- a/library/type.md +++ /dev/null @@ -1,77 +0,0 @@ -# Type - -Namespace `Chevere\Type` - -The Type component is in charge of providing a layer for dynamic type handling. - -## Creating Type - -A Type gets created by passing a `type` [keyword](#type-keywords). - -```php -use Chevere\Type\Type; - -$type = new Type(Type::STRING); -``` - -## Type keywords - -Available keywords: - -- `Type::ARRAY` -- `Type::BOOLEAN` -- `Type::CALLABLE` -- `Type::FLOAT` -- `Type::INTEGER` -- `Type::ITERABLE` -- `Type::NULL` -- `Type::OBJECT` -- `Type::RESOURCE` -- `Type::STRING` - -💡 Full-qualified **class names** and **interface names** can be passed as type keyword. - -## Primitive & Type-hinting - -The return values for methods `primitive` and `typeHinting` is explained in the table below: - -| Type | primitive() | typeHinting() | -| ------------- | --------------- | --------------- | -| keyword | `keyword` | `keyword` | -| SomeClass | `className` | `SomeClass` | -| SomeInterface | `interfaceName` | `SomeInterface` | - -For [keywords](#type-keywords), the return value of `primitive` and `typeHinting` is same as the keyword. - -## Validator - -The `validator` method provides access to the callable used to primitive validate the type. - -```php -use Chevere\Type\Type; - -$type = new Type(Type::INTEGER); -$callable = $type->validator(); -// is_int -``` - -## Validate - -The `validate` method allows to validate any `$var` against the declared type. - -```php -$boolean = $type->validate($var); -``` - -## Check if is scalar - -The `isScalar` method returns true if the type is of type scalar. - -```php -use Chevere\Type\Type; - -$integerType = new Type(Type::INTEGER); -$true = $integerType->isScalar(); -$objectType = new Type(Type::OBJECT); -$false = $type->isScalar(); -``` diff --git a/library/filesystem.md b/packages/filesystem.md similarity index 95% rename from library/filesystem.md rename to packages/filesystem.md index 4c006a21..4ac7a662 100644 --- a/library/filesystem.md +++ b/packages/filesystem.md @@ -1,8 +1,12 @@ # Filesystem -Namespace `Chevere\Filesystem` +## Summary -The Filesystem component is in charge of interact with the filesystem, offering a myriad of related functionalities. +Filesystem related functionalities. + +## Installing + +Filesystem is available through [Packagist](https://packagist.org/packages/chevere/filesystem) and the repository source is at [chevere/filesystem](https://github.com/chevere/filesystem). ## Path @@ -123,7 +127,7 @@ $boolean = $directory->exists(); The `assertExists` method asserts if the directory exists. Throws exception when the directory doesn't exists in the filesystem. ```php -use Chevere\Exceptions\Filesystem\DirNotExistsException; +use Chevere\Filesystem\Exceptions\DirNotExistsException; $directory->assertExists(); // Throws DirNotExistsException ``` diff --git a/packages/naming.php b/packages/naming.php index 88c30969..69afe16f 100644 --- a/packages/naming.php +++ b/packages/naming.php @@ -19,4 +19,5 @@ 'writer.md' => 'Writer', 'xrdebug.md' => 'xrDebug', 'sql2p.md' => 'SQL2P', + 'var-support.md' => 'VarSupport', ]; diff --git a/packages/sql2p.md b/packages/sql2p.md index 739011cf..3b49dd03 100644 --- a/packages/sql2p.md +++ b/packages/sql2p.md @@ -4,7 +4,7 @@ ## Summary -SQL2P generates [Parameter(s)](https://chevere.org/library/parameter) for MySQL schemas. It represents database tables and its columns using the Parameter package. +SQL2P generates [Parameter(s)](https://chevere.org/packages/parameter) for MySQL schemas. It represents database tables and its columns using the Parameter package. ## Installing diff --git a/library/standard.md b/packages/standard.md similarity index 89% rename from library/standard.md rename to packages/standard.md index bfed54ce..55c674ca 100644 --- a/library/standard.md +++ b/packages/standard.md @@ -1,8 +1,14 @@ # Standard -Namespace `Chevere\Standard` +## Summary -The Standard component provides improvements and alternatives to PHP's standard function library. +Improvements and alternatives to PHP's standard function library. + +## Installing + +Standard is available through [Packagist](https://packagist.org/packages/chevere/standard) and the repository source is at [chevere/standard](https://github.com/chevere/standard). + +The Standard component . ## arrayFilterBoth diff --git a/library/variable-support.md b/packages/var-support.md similarity index 76% rename from library/variable-support.md rename to packages/var-support.md index d4bd5162..06561bf5 100644 --- a/library/variable-support.md +++ b/packages/var-support.md @@ -1,8 +1,12 @@ -# VariableSupport +# VarSupport -Namespace `Chevere\VariableSupport` +## Summary -The VariableSupport component is in charge of providing extra tools for handling variables. +Extra tools for handling variables. + +## Installing + +VarSupport is available through [Packagist](https://packagist.org/packages/chevere/var-support) and the repository source is at [chevere/var-support](https://github.com/chevere/var-support). ## ObjectVariable @@ -11,7 +15,7 @@ The `ObjectVariable` component is in charge of handling an object variable. ### Creating ObjectVariable ```php -use Chevere\VariableSupport\ObjectVariable; +use Chevere\VarSupport\ObjectVariable; $object = new ObjectVariable($var); $var = $object->variable(); @@ -34,7 +38,7 @@ A storable variable for Chevere is any PHP variable that can be stored as a stri ### Creating StorableVariable ```php -use Chevere\VariableSupport\StorableVariable; +use Chevere\VarSupport\StorableVariable; $storable = new StorableVariable($var); $var = $storable->variable();