From 33a415b1f163447de96ce3a0efd8f3233883ef81 Mon Sep 17 00:00:00 2001 From: Massimiliano Braglia Date: Wed, 6 Feb 2019 14:15:34 +0100 Subject: [PATCH 1/3] Begun docs --- docs/annotations.md | 4 ++++ docs/aql.md | 4 ++++ docs/doctrine-features.md | 4 ++++ docs/form-features.md | 4 ++++ docs/getting-started.md | 24 ++++++++++++++++++++++++ docs/pagination-continuation-token.md | 4 ++++ docs/patch-manager.md | 4 ++++ docs/request-body-converters.md | 4 ++++ 8 files changed, 52 insertions(+) create mode 100644 docs/annotations.md create mode 100644 docs/aql.md create mode 100644 docs/doctrine-features.md create mode 100644 docs/form-features.md create mode 100644 docs/getting-started.md create mode 100644 docs/pagination-continuation-token.md create mode 100644 docs/patch-manager.md create mode 100644 docs/request-body-converters.md diff --git a/docs/annotations.md b/docs/annotations.md new file mode 100644 index 0000000..d2ef69e --- /dev/null +++ b/docs/annotations.md @@ -0,0 +1,4 @@ +Fazland - ApiPlatformBundle - Annotations +========================================= + +Work in progress diff --git a/docs/aql.md b/docs/aql.md new file mode 100644 index 0000000..6cbcf08 --- /dev/null +++ b/docs/aql.md @@ -0,0 +1,4 @@ +Fazland - ApiPlatformBundle - AQL (ApiPlatformBundle Query Language) +==================================================================== + +Work in progress diff --git a/docs/doctrine-features.md b/docs/doctrine-features.md new file mode 100644 index 0000000..683c06d --- /dev/null +++ b/docs/doctrine-features.md @@ -0,0 +1,4 @@ +Fazland - ApiPlatformBundle - Doctrine Features +=============================================== + +Work in progress diff --git a/docs/form-features.md b/docs/form-features.md new file mode 100644 index 0000000..c76f3f7 --- /dev/null +++ b/docs/form-features.md @@ -0,0 +1,4 @@ +Fazland - ApiPlatformBundle - Form Features +=========================================== + +Work in progress diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..74d1b08 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,24 @@ +Fazland - ApiPlatformBundle +=========================== + +ApiPlatformBundle is a Symfony bundle that helps you building RESTful API within your application. +Just register in the `bundles.php` the bundle and you'll have all the features available. +```php + ['all' => true], + // [...] +]; +``` + +What comes with ApiPlatformBundle? +---------------------------------- +- [Doctrine's ORM/ODM features](./doctrine-features.md) +- [Form features](./form-features.md) +- [Request body converters](./request-body-converters.md) +- [PatchManager](./patch-manager.md) +- [Annotations](./annotations.md) +- [Pagination and continuation token](./pagination-continuation-token.md) +- [AQL (ApiPlatformBundle Query language)](./aql.md) diff --git a/docs/pagination-continuation-token.md b/docs/pagination-continuation-token.md new file mode 100644 index 0000000..264ec40 --- /dev/null +++ b/docs/pagination-continuation-token.md @@ -0,0 +1,4 @@ +Fazland - ApiPlatformBundle - Pagination and continuation token +=============================================================== + +Work in progress diff --git a/docs/patch-manager.md b/docs/patch-manager.md new file mode 100644 index 0000000..dea329d --- /dev/null +++ b/docs/patch-manager.md @@ -0,0 +1,4 @@ +Fazland - ApiPlatformBundle - Patch Manager +=========================================== + +Work in progress diff --git a/docs/request-body-converters.md b/docs/request-body-converters.md new file mode 100644 index 0000000..aacca9f --- /dev/null +++ b/docs/request-body-converters.md @@ -0,0 +1,4 @@ +Fazland - ApiPlatformBundle - Request Body Converters +===================================================== + +Work in progress From 6d4bc622952477c1492db47db0fcd2a5d04629d7 Mon Sep 17 00:00:00 2001 From: Massimiliano Braglia Date: Wed, 13 Feb 2019 14:49:18 +0100 Subject: [PATCH 2/3] doctrine-features.md section --- docs/doctrine-features.md | 103 +++++++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/docs/doctrine-features.md b/docs/doctrine-features.md index 683c06d..76e5060 100644 --- a/docs/doctrine-features.md +++ b/docs/doctrine-features.md @@ -1,4 +1,105 @@ Fazland - ApiPlatformBundle - Doctrine Features =============================================== -Work in progress +This bundle introduce some [Doctrine](https://github.com/doctrine/orm) features and helpers. + +`objects` is often a shortcut reference to `entities` or `documents`. + +EntityIterator and DocumentIterator +--------------------------------------- +Given an instance of `Doctrine\ORM\QueryBuilder` or `Doctrine\ODM\MongoDB\Query\Builder` the iterator allows you to iterate a single entity/document query confortably: + +ORM +```php +use App\Entity\User; +use Doctrine\ORM\EntityManagerInterface; +use Fazland\ApiPlatformBundle\Doctrine\ORM\EntityIterator; + +/** @var EntityManagerInterface $em */ +$em = // The EntityManagerInterface instance. +$qb = $em->createQueryBuilder(); +$qb + ->select('u') + ->from(User::class, 'u') +; + +$users = new EntityIterator($qb); +foreach ($users as $user) { + var_dump($user instanceof User); +} +``` + +MongoDB: +```php +use App\Document\User; +use Doctrine\ODM\MongoDB\DocumentManager; +use Fazland\ApiPlatformBundle\Doctrine\Mongo\DocumentIterator; + +/** @var DocumentManager $dm */ +$dm = // The EntityManagerInterface instance. +$qb = $dm->createQueryBuilder(User::class); + +$users = new DocumentIterator($qb); +foreach ($users as $user) { + var_dump($user instanceof User); +} +``` + +EntityRepository and DocumentRepository +--------------------------------------- +These two classes are just an extension of the base Doctrine Repository class with some utility methods: +```php +public function all(): ObjectIterator +``` +returns all objects matching that object. + +```php +public function count(array $criteria = []): int +``` +returns an integer representing the count of all objects matching the given criteria. + +```php +public function findOneByCached(array $criteria, array $orderBy = null, int $ttl = 28800) +``` +executes the base `findOneBy` and caches the results. + +```php +public function findByCached(array $criteria, ?array $orderBy = null, ?int $limit = null, ?int $offset = null, int $ttl = 28800) +``` +executes the base `findBy` method and caches the results. + +```php +public function get($id, $lockMode = null, $lockVersion = null) +``` +executes the base `find` method and throws a `NoResultException` if no result has been found. + +```php +public function getOneBy(array $criteria, ?array $orderBy = null) +``` +executes the base `findOneBy` method and throws a `NoResultException` if no result has been found. + +```php +public function getOneByCached(array $criteria, ?array $orderBy = null, int $ttl = 28800) +``` + +executes the `findOneByCached` method and throws a `NoResultException` if no result has been found. + +Unfortunately, `Doctrine\ODM\MongoDB` does not support cache. + +How to use +---------- +Just set the `default_repository_class` in the Doctrine configuration: + +ORM +```yaml +doctrine: + orm: + default_repository_class: Fazland\ApiPlatformBundle\Doctrine\ORM\EntityRepository +``` + +MongoDB: +```yaml +doctrine_mongodb: + document_managers: + default_repository_class: Fazland\ApiPlatformBundle\Doctrine\Mongo\DocumentRepository +``` From 1b85b6659babc44081614d71d0711a701d66709f Mon Sep 17 00:00:00 2001 From: Massimiliano Braglia Date: Wed, 13 Nov 2019 18:05:41 +0100 Subject: [PATCH 3/3] Removed doctrine-features.md and added form-features.md --- docs/doctrine-features.md | 105 -------------------------------------- docs/form-features.md | 57 ++++++++++++++++++++- docs/getting-started.md | 1 - 3 files changed, 56 insertions(+), 107 deletions(-) delete mode 100644 docs/doctrine-features.md diff --git a/docs/doctrine-features.md b/docs/doctrine-features.md deleted file mode 100644 index 76e5060..0000000 --- a/docs/doctrine-features.md +++ /dev/null @@ -1,105 +0,0 @@ -Fazland - ApiPlatformBundle - Doctrine Features -=============================================== - -This bundle introduce some [Doctrine](https://github.com/doctrine/orm) features and helpers. - -`objects` is often a shortcut reference to `entities` or `documents`. - -EntityIterator and DocumentIterator ---------------------------------------- -Given an instance of `Doctrine\ORM\QueryBuilder` or `Doctrine\ODM\MongoDB\Query\Builder` the iterator allows you to iterate a single entity/document query confortably: - -ORM -```php -use App\Entity\User; -use Doctrine\ORM\EntityManagerInterface; -use Fazland\ApiPlatformBundle\Doctrine\ORM\EntityIterator; - -/** @var EntityManagerInterface $em */ -$em = // The EntityManagerInterface instance. -$qb = $em->createQueryBuilder(); -$qb - ->select('u') - ->from(User::class, 'u') -; - -$users = new EntityIterator($qb); -foreach ($users as $user) { - var_dump($user instanceof User); -} -``` - -MongoDB: -```php -use App\Document\User; -use Doctrine\ODM\MongoDB\DocumentManager; -use Fazland\ApiPlatformBundle\Doctrine\Mongo\DocumentIterator; - -/** @var DocumentManager $dm */ -$dm = // The EntityManagerInterface instance. -$qb = $dm->createQueryBuilder(User::class); - -$users = new DocumentIterator($qb); -foreach ($users as $user) { - var_dump($user instanceof User); -} -``` - -EntityRepository and DocumentRepository ---------------------------------------- -These two classes are just an extension of the base Doctrine Repository class with some utility methods: -```php -public function all(): ObjectIterator -``` -returns all objects matching that object. - -```php -public function count(array $criteria = []): int -``` -returns an integer representing the count of all objects matching the given criteria. - -```php -public function findOneByCached(array $criteria, array $orderBy = null, int $ttl = 28800) -``` -executes the base `findOneBy` and caches the results. - -```php -public function findByCached(array $criteria, ?array $orderBy = null, ?int $limit = null, ?int $offset = null, int $ttl = 28800) -``` -executes the base `findBy` method and caches the results. - -```php -public function get($id, $lockMode = null, $lockVersion = null) -``` -executes the base `find` method and throws a `NoResultException` if no result has been found. - -```php -public function getOneBy(array $criteria, ?array $orderBy = null) -``` -executes the base `findOneBy` method and throws a `NoResultException` if no result has been found. - -```php -public function getOneByCached(array $criteria, ?array $orderBy = null, int $ttl = 28800) -``` - -executes the `findOneByCached` method and throws a `NoResultException` if no result has been found. - -Unfortunately, `Doctrine\ODM\MongoDB` does not support cache. - -How to use ----------- -Just set the `default_repository_class` in the Doctrine configuration: - -ORM -```yaml -doctrine: - orm: - default_repository_class: Fazland\ApiPlatformBundle\Doctrine\ORM\EntityRepository -``` - -MongoDB: -```yaml -doctrine_mongodb: - document_managers: - default_repository_class: Fazland\ApiPlatformBundle\Doctrine\Mongo\DocumentRepository -``` diff --git a/docs/form-features.md b/docs/form-features.md index c76f3f7..35985c8 100644 --- a/docs/form-features.md +++ b/docs/form-features.md @@ -1,4 +1,59 @@ Fazland - ApiPlatformBundle - Form Features =========================================== -Work in progress +This bundle introduce some [Symfony Form](https://github.com/symfony/form) features: + +Types +----- +#### `Fazland\ApiPlatformBundle\Form\CheckboxType` +Type that extends the Symfony base type with the `false_values` options set to `['0', 'false', 'no', 'off', 'n', 'f']` + +#### `Fazland\ApiPlatformBundle\Form\CollectionType` +Type that extends the Symfony base type with the `allow_add`, `allow_delete`, `delete_empty` options set to `true` and `error_bubbling` to false. + +#### `Fazland\ApiPlatformBundle\Form\IsoDateTimeType` and `Fazland\ApiPlatformBundle\Form\IsoDateTimeImmutableType` +Type with the `DateTimeToIso8601Transformer` view transformer already set. + +#### `Fazland\ApiPlatformBundle\Form\PageTokenType` +This type accepts a valid `Fazland\ApiPlatformBundle\Pagination\PageToken` string representation. `Fazland\ApiPlatformBundle\Pagination\PageToken` are discussed into the [Pagination and continuation token](./pagination-continuation-token.md) section. + +#### `Fazland\ApiPlatformBundle\Form\TelType` +Type with the `PhoneNumberToStringTransformer` view transformer already set. + +#### `Fazland\ApiPlatformBundle\Form\UnstructuredType` +This type accepts any data. This is suitable if you don't have a structure or you don't want to specify the single fields on it. + +Transformers +------------ +#### `Fazland\ApiPlatformBundle\Form\DataTransformer\Money\CodeToCurrencyTransformer` +Transforms a valid currency ISO string into a valid `Money\Currency` object. + +#### `Fazland\ApiPlatformBundle\Form\DataTransformer\Money\MoneyTransformer` +Transforms an array with keys `amount` and `currency` into a valid `Money\Money` object. + +#### `Fazland\ApiPlatformBundle\Form\DataTransformer\Base64ToUploadedFileTransformer` +Transforms a data uri string into an instance of `UploadedFile`. + +#### `Fazland\ApiPlatformBundle\Form\DataTransformer\BooleanTransformer` +Transforms `['1', 'true', 'yes', 'on', 'y', 't']` as true values and `['0', 'false', 'no', 'off', 'n', 'f']` as false values. + +#### `Fazland\ApiPlatformBundle\Form\DataTransformer\BooleanTransformer` +Accepts at its construction a list of transformers and use those one by one to transform the passed values. + +#### `Fazland\ApiPlatformBundle\Form\DataTransformer\DateTimeToIso8601Transformer` and `Fazland\ApiPlatformBundle\Form\DataTransformer\DateTransformer` +Accepts strings in some date formats and transform those into valid `\DateTimeInterface` instances. + +#### `Fazland\ApiPlatformBundle\Form\DataTransformer\IntegerTransformer` +Accepts numeric strings and transform it into valid integers. + +#### `Fazland\ApiPlatformBundle\Form\DataTransformer\MappingTransformer` +Accepts a transformer at its construction and applies it for each value passed. + +#### `Fazland\ApiPlatformBundle\Form\DataTransformer\NullableMappingTransformer` +As above but returns null if the value is null. + +#### `Fazland\ApiPlatformBundle\Form\DataTransformer\PageTokenTransformer` +Transforms a `PageToken` instance into a string and vice versa. + +#### `Fazland\ApiPlatformBundle\Form\DataTransformer\PhoneNumberToString` +Transforms a `PhoneNumber` instance into a string and vice versa. diff --git a/docs/getting-started.md b/docs/getting-started.md index 74d1b08..cd0c4a8 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -15,7 +15,6 @@ return [ What comes with ApiPlatformBundle? ---------------------------------- -- [Doctrine's ORM/ODM features](./doctrine-features.md) - [Form features](./form-features.md) - [Request body converters](./request-body-converters.md) - [PatchManager](./patch-manager.md)