docs: executable guides

soyuka · Aug 3, 2023 · 6cf0d07 · 6cf0d07
1 parent b8ca845
commit 6cf0d07
Show file tree

Hide file tree

Showing 77 changed files with 5,805 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: Generate Documentation
+        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: Update project dependencies
+                run: composer update --no-interaction --no-progress --ansi
+
+            -   name: Test guides
+                working-directory: docs
+                env:
+                    PDG_AUTOLOAD: ./vendor/autoload.php
+                    KERNEL_CLASS: \ApiPlatform\Playground\Kernel
+                run: |
+                    for d in guide/*.php; do
+                      pdg-phpunit $d
+                    done
+            -   name: Generate Guides
+                working-directory: docs
+                run: |
+                    for d in guide/*.php; do
+                      name=$(basename $d .php);
+                      pdg guide "$d" > "pages/guide/$name.mdx";
+                    done
+
diff --git a/composer.json b/composer.json
@@ -85,7 +85,8 @@
         "symfony/web-profiler-bundle": "^6.1",
         "symfony/yaml": "^6.1",
         "twig/twig": "^1.42.3 || ^2.12 || ^3.0",
-        "webonyx/graphql-php": "^14.0 || ^15.0"
+        "webonyx/graphql-php": "^14.0 || ^15.0",
+        "zenstruck/foundry": "^1.28"
     },
     "conflict": {
         "doctrine/common": "<3.2.2",
@@ -135,7 +136,8 @@
         "sort-packages": true,
         "allow-plugins": {
             "composer/package-versions-deprecated": true,
-            "phpstan/extension-installer": true
+            "phpstan/extension-installer": true,
+            "symfony/runtime": true
         }
     },
     "extra": {

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,56 @@
+{
+    "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": "dev-docs",
+        "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"
+    }
+}
diff --git a/docs/config/bundles.php b/docs/config/bundles.php
@@ -0,0 +1,12 @@
+<?php
+
+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,5 @@
+<?php
+
+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).