docs: executable guides (api-platform#5712)

Romaixn · Oct 3, 2023 · 130eb6f · 130eb6f
1 parent 15e66f6
commit 130eb6f
Show file tree

Hide file tree

Showing 78 changed files with 5,813 additions and 120 deletions.
diff --git a/.github/workflows/guides.yaml b/.github/workflows/guides.yaml
@@ -0,0 +1,62 @@
+name: Guides
+
+on:
+    push:
+    pull_request:
+
+env:
+    COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    COVERAGE: '0'
+    SYMFONY_DEPRECATIONS_HELPER: max[self]=0
+
+jobs:
+    docs:
+        name: Test guides
+        runs-on: ubuntu-latest
+        steps:
+            -   name: Checkout
+                uses: actions/checkout@v3
+            -   name: Setup PHP with pre-release PECL extension
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: 8.2
+                    tools: pecl, composer
+                    extensions: intl, bcmath, curl, openssl, mbstring, pdo_sqlite
+                    coverage: none
+                    ini-values: memory_limit=-1
+            -   name: Get composer cache directory
+                id: composercache
+                run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+                shell: bash
+            -   name: Global require pdg
+                run: |
+                    cd $(composer -n config --global home)
+                    echo "{\"repositories\":[{\"type\":\"vcs\",\"url\":\"https://github.com/php-documentation-generator/php-documentation-generator\"}]}" > composer.json
+                    composer global config --no-plugins allow-plugins.symfony/runtime true
+                    composer global require php-documentation-generator/php-documentation-generator:dev-main
+            -   name: Cache dependencies
+                uses: actions/cache@v3
+                with:
+                    path: ${{ steps.composercache.outputs.dir }}
+                    key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
+                    restore-keys: ${{ runner.os }}-composer-
+            -   name: Install project dependencies
+                working-directory: docs
+                run: composer install --no-interaction --no-progress --ansi
+            -   name: Test guides
+                working-directory: docs
+                env:
+                    APP_DEBUG: 0
+                    PDG_AUTOLOAD: ${{ github.workspace }}/docs/vendor/autoload.php
+                    KERNEL_CLASS: \ApiPlatform\Playground\Kernel
+                run: |
+                    for d in guides/*.php; do
+                      rm -f var/data.db
+                      echo "Testing guide $d"
+                      pdg-phpunit $d
+                      code=$?
+                      if [[ $code -ne 0 ]]; then
+                        break
+                      fi
+                    done
+                    exit $code
diff --git a/.php-cs-fixer.dist.php b/.php-cs-fixer.dist.php
@@ -16,6 +16,7 @@
     ->exclude([
         'src/Core/Bridge/Symfony/Maker/Resources/skeleton',
         'tests/Fixtures/app/var',
+        'docs/guides',
     ])
     ->notPath('src/Symfony/Bundle/DependencyInjection/Configuration.php')
     ->notPath('src/Annotation/ApiFilter.php') // temporary

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,15 @@
+pages/guide/**/*.mdx
+pages/reference/**/*.mdx
+pages/tutorial/**/*.mdx
+pages/core
+pages/create-client
+pages/deployment
+pages/distribution
+pages/extra
+pages/schema-generator
+pages/sidebar.mdx
+.next
+node_modules
+composer.lock
+vendor
+var
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,17 @@
+# API Platform documentation
+
+## Guides
+
+A guide is a PHP executable file that will be transformed into documentation. It follows [Diataxis How-To Guides](https://diataxis.fr/how-to-guides/) practice which is a must read before writing a guide.
+
+Guides are transformed to Markdown using [php-documentation-generator](https://github.com/php-documentation-generator/php-documentation-generator) which is merely a version of [docco](https://ashkenas.com/docco/) in PHP adapted to output markdown. 
+
+## WASM
+
+Guides are executable in a browser environment and need to be preloaded using:
+
+```
+docker run -v $(pwd):/src -v $(pwd)/public/php-wasm:/public -w /public php-wasm python3 /emsdk/upstream/emscripten/tools/file_packager.py php-web.data --preload "/src" --js-output=php-web.data.js --no-node --exclude '*Tests*' '*features*' '*public*' '*/.*'
+```
+
+A build of [php-wasm](https://github.com/soyuka/php-wasm) is needed in the `public/php-wasm` directory to try it out.
diff --git a/docs/composer.json b/docs/composer.json
@@ -0,0 +1,57 @@
+{
+    "name": "api-platform/playground",
+    "description": "API Platform wasm playground",
+    "type": "project",
+    "license": "MIT",
+    "autoload": {
+        "psr-4": {
+            "ApiPlatform\\Playground\\": "src/"
+        }
+    },
+    "authors": [
+        {
+            "name": "soyuka",
+            "email": "soyuka@users.noreply.github.com"
+        }
+    ],
+    "require": {
+        "api-platform/core": "*",
+        "symfony/expression-language": "6.2.*",
+        "nelmio/cors-bundle": "^2.2",
+        "phpstan/phpdoc-parser": "^1.15",
+        "symfony/framework-bundle": "6.2.*",
+        "symfony/property-access": "6.2.*",
+        "symfony/property-info": "6.2.*",
+        "symfony/runtime": "6.2.*",
+        "symfony/security-bundle": "6.2.*",
+        "symfony/serializer": "6.2.*",
+        "symfony/validator": "6.2.*",
+        "symfony/yaml": "^6.2",
+        "doctrine/orm": "^2.14",
+        "doctrine/doctrine-migrations-bundle": "^3.2",
+        "doctrine/doctrine-bundle": "^2.9",
+        "doctrine/doctrine-fixtures-bundle": "^3.4",
+        "zenstruck/foundry": "^1.31",
+        "symfony/http-client": "^6.2",
+        "symfony/browser-kit": "^6.2",
+        "justinrainbow/json-schema": "^5.2"
+    },
+    "repositories": [
+        {
+            "type": "path",
+            "url": "../",
+            "options": {
+                "symlink": false
+            }
+        }
+    ],
+    "config": {
+        "allow-plugins": {
+            "symfony/runtime": true
+        }
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^10"
+    },
+    "minimum-stability": "dev"
+}
diff --git a/docs/config/bundles.php b/docs/config/bundles.php
@@ -0,0 +1,23 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+return [
+    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
+    // Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
+    Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
+    Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
+    Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle::class => ['all' => true],
+    Nelmio\CorsBundle\NelmioCorsBundle::class => ['all' => true],
+    ApiPlatform\Symfony\Bundle\ApiPlatformBundle::class => ['all' => true],
+    Zenstruck\Foundry\ZenstruckFoundryBundle::class => ['all' => true],
+];
diff --git a/docs/config/packages/doctrine.yaml b/docs/config/packages/doctrine.yaml
@@ -0,0 +1,7 @@
+doctrine:
+  dbal:
+    url: 'sqlite:///%kernel.project_dir%/var/data.db'
+  orm:
+    auto_generate_proxy_classes: true
+    naming_strategy: doctrine.orm.naming_strategy.underscore_number_aware
+    auto_mapping: false
diff --git a/docs/config/packages/doctrine_migrations.yaml b/docs/config/packages/doctrine_migrations.yaml
@@ -0,0 +1,6 @@
+doctrine_migrations:
+  migrations_paths:
+    # namespace is arbitrary but should be different from App\Migrations
+    # as migrations classes should NOT be autoloaded
+    'DoctrineMigrations': '%kernel.project_dir%/migrations'
+  enable_profiler: false
diff --git a/docs/config/packages/framework.yaml b/docs/config/packages/framework.yaml
@@ -0,0 +1,3 @@
+when@test:
+    framework:
+        test: true
diff --git a/docs/config/preload.php b/docs/config/preload.php
@@ -0,0 +1,16 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+if (file_exists(dirname(__DIR__).'/var/cache/prod/App_KernelProdContainer.preload.php')) {
+    require dirname(__DIR__).'/var/cache/prod/App_KernelProdContainer.preload.php';
+}
diff --git a/docs/config/routes/api_platform.yaml b/docs/config/routes/api_platform.yaml
@@ -0,0 +1,4 @@
+api_platform:
+    resource: .
+    type: api_platform
+    prefix: /
diff --git a/docs/config/routes/framework.yaml b/docs/config/routes/framework.yaml
@@ -0,0 +1,4 @@
+when@dev:
+    _errors:
+        resource: '@FrameworkBundle/Resources/config/routing/errors.xml'
+        prefix: /_error
diff --git a/docs/config/services.yaml b/docs/config/services.yaml
@@ -0,0 +1,11 @@
+services:
+    _defaults:
+        autowire: true
+        autoconfigure: true
+    App\:
+        resource: '../src/'
+        exclude:
+            - '../src/DependencyInjection/'
+            - '../src/Entity/'
+            - '../src/Kernel.php'
+            - '../src/guide.php'
diff --git a/docs/guides/collect-denormalization-errors.php b/docs/guides/collect-denormalization-errors.php
@@ -0,0 +1,46 @@
+<?php
+// --- 
+// slug: collecting-denormalization-errors
+// name: Collecting Denormalization Errors
+// executable: true
+// tags: serializer
+// ---
+
+// # Collecting Denormalization Errors
+namespace App\ApiResource;
+
+use ApiPlatform\Metadata\ApiResource;
+
+// When submitting data you can collect denormalization errors using the [COLLECT_DENORMALIZATION_ERRORS option](https://symfony.com/doc/current/components/serializer.html#collecting-type-errors-while-denormalizing).
+// To do so enable the [`collectDenormalizationErrors`](/docs/Metadata/AttributeResource#collectDenormalizationErrors) option.
+#[ApiResource(
+    collectDenormalizationErrors: true
+)]
+class Book
+{
+    public ?bool $boolean;
+    public ?string $property1;
+}
+
+// If the submitted data has denormalization errors, the HTTP status code will be set to `422 Unprocessable Content` and the response body will contain the list of errors:
+// ```json
+// {
+//     "@context": "/api/contexts/ConstraintViolationList",
+//     "@type": "ConstraintViolationList",
+//     "hydra:title": "An error occurred",
+//     "hydra:description": "boolean: This value should be of type bool.\nproperty1: This value should be of type string.",
+//     "violations": [
+//         {
+//             "propertyPath": "boolean",
+//             "message": "This value should be of type bool.",
+//             "code": "0"
+//         },
+//         {
+//             "propertyPath": "property1",
+//             "message": "This value should be of type string.",
+//             "code": "0"
+//         }
+//     ]
+// }
+// ```
+// You can also enable collecting of denormalization errors globally in the [Global Resources Defaults](https://api-platform.com/docs/core/configuration/#global-resources-defaults).