ci: check guides

.github/workflows/ci.yml

@@ -728,3 +728,36 @@ jobs:
         run: tests/Fixtures/app/console cache:clear --ansi
       - name: Run Behat tests
         run: vendor/bin/behat --out=std --format=progress --profile=default --no-interaction
+
+  checkguide:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        php:
+          - '8.1'
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: intl, bcmath, curl, openssl, mbstring
+          ini-values: memory_limit=-1
+          tools: pecl, composer
+          coverage: none
+      - name: Get composer cache directory
+        id: composercache
+        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+      - 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: cd docs && composer update --no-interaction --no-progress --ansi
+      - name: Run check command
+        run: cd docs && make check

docs/.env

@@ -0,0 +1,24 @@
+# In all environments, the following files are loaded if they exist,
+# the latter taking precedence over the former:
+#
+#  * .env                contains default values for the environment variables needed by the app
+#  * .env.local          uncommitted file with local overrides
+#  * .env.$APP_ENV       committed environment-specific defaults
+#  * .env.$APP_ENV.local uncommitted environment-specific overrides
+#
+# Real environment variables win over .env files.
+#
+# DO NOT DEFINE PRODUCTION SECRETS IN THIS FILE NOR IN ANY OTHER COMMITTED FILES.
+# https://symfony.com/doc/current/configuration/secrets.html
+#
+# Run "composer dump-env prod" to compile .env files for production use (requires symfony/flex >=1.2).
+# https://symfony.com/doc/current/best_practices.html#use-environment-variables-for-infrastructure-configuration
+
+###> symfony/framework-bundle ###
+APP_ENV=dev
+APP_SECRET=ab0da85135bd245202dd6c8de5b90aa9
+###< symfony/framework-bundle ###
+
+###> nelmio/cors-bundle ###
+CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'
+###< nelmio/cors-bundle ###

docs/.env.test

@@ -0,0 +1,6 @@
+# define your env variables for the test env here
+KERNEL_CLASS='App\Kernel'
+APP_SECRET='$ecretf0rt3st'
+SYMFONY_DEPRECATIONS_HELPER=999999
+PANTHER_APP_ENV=panther
+PANTHER_ERROR_SCREENSHOT_DIR=./var/error-screenshots

docs/.gitignore

@@ -0,0 +1,29 @@
+pages/guide/**/*.mdx
+pages/reference/**/*.mdx
+pages/tutorial/**/*.mdx
+pages/sidebar.mdx
+.next
+node_modules
+composer.lock
+vendor
+var
+
+###> symfony/framework-bundle ###
+/.env.local
+/.env.local.php
+/.env.*.local
+/config/secrets/prod/prod.decrypt.private.php
+/public/bundles/
+/var/
+/vendor/
+###< symfony/framework-bundle ###
+
+###> phpunit/phpunit ###
+/phpunit.xml
+.phpunit.result.cache
+###< phpunit/phpunit ###
+
+###> symfony/phpunit-bridge ###
+.phpunit.result.cache
+/phpunit.xml
+###< symfony/phpunit-bridge ###

docs/Makefile

@@ -0,0 +1,25 @@
+.PHONY: guide index references clean
+
+all: guide references index 
+
+guide:
+	for d in ./guide/*.php; do \
+			name=$$(basename $$d .php); \
+			./bin/pdg pdg:guide "$$d" > "pages/guide/$$name.mdx"; \
+	done
+
+check:
+	for d in ./guide/*.php; do \
+			name=$$(basename $$d .php); \
+			./bin/pdg pdg:check:guide "$$d"; \
+	done
+
+index:
+	./bin/pdg pdg:index > "pages/sidebar.mdx"
+
+references:
+	./bin/pdg pdg:references
+
+clean:
+	rm -r pages/reference/*
+	rm pages/guide/*.mdx

docs/bin/pdg

@@ -0,0 +1,17 @@
+#!/usr/bin/env php
+<?php
+
+use PDG\Kernel;
+use Symfony\Bundle\FrameworkBundle\Console\Application;
+
+if (!is_file(dirname(__DIR__).'/vendor/autoload_runtime.php')) {
+    throw new LogicException('Symfony Runtime is missing. Try running "composer require symfony/runtime".');
+}
+
+require_once dirname(__DIR__).'/vendor/autoload_runtime.php';
+
+return function (array $context, string $guide = '') {
+    $kernel = new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG'], $guide);
+
+    return new Application($kernel);
+};

docs/composer.json

@@ -0,0 +1,67 @@
+{
+    "name": "api-platform/pdg",
+    "description": "PHP Documentation Generator",
+    "authors": [
+        {
+            "name": "soyuka",
+            "email": "soyuka@users.noreply.github.com"
+        }
+    ],
+    "autoload": {
+        "psr-4": {
+            "PDG\\": "src/",
+            "ApiPlatform\\": "../src"
+        },
+        "files": [
+            "src/Command/CheckGuideCommand.php",
+            "src/Command/PhpUnitCommand.php",
+            "src/Command/TestGuideCommand.php"
+        ]
+    },
+    "require-dev": {
+        "symfony/dom-crawler": "^6.2",
+        "phpstan/phpdoc-parser": "^1.15",
+        "symfony/serializer": "^6.2",
+        "nikic/php-parser": "^4.15",
+        "dama/doctrine-test-bundle": "^7.1",
+        "justinrainbow/json-schema": "^5.2",
+        "phpunit/phpunit": "^9.5",
+        "symfony/browser-kit": "^6.2",
+        "symfony/css-selector": "^6.2",
+        "symfony/http-client": "^6.2",
+        "symfony/phpunit-bridge": "^6.2"
+    },
+    "require": {
+        "symfony/runtime": "^6.2",
+        "symfony/console": "^6.2",
+        "symfony/http-kernel": "^6.2",
+        "symfony/framework-bundle": "^6.2",
+        "spatie/yaml-front-matter": "^2.0",
+        "symfony/property-info": "^6.2",
+        "symfony/property-access": "^6.2",
+        "symfony/flex": "^2.2",
+        "nelmio/cors-bundle": "^2.2",
+        "symfony/security-bundle": "^6.2",
+        "willdurand/negotiation": "^3.1",
+        "symfony/twig-bundle": "^6.2",
+        "symfony/web-link": "^6.2",
+        "doctrine/annotations": "^2.0",
+        "doctrine/doctrine-bundle": "^2.8",
+        "doctrine/doctrine-migrations-bundle": "^3.2",
+        "doctrine/orm": "^2.14",
+        "doctrine/doctrine-fixtures-bundle": "^3.4",
+        "symfony/validator": "^6.2"
+    },
+    "config": {
+        "allow-plugins": {
+            "symfony/runtime": true,
+            "symfony/flex": true
+        }
+    },
+    "scripts": {
+        "auto-scripts": {
+            "cache:clear": "symfony-cmd",
+            "assets:install %PUBLIC_DIR%": "symfony-cmd"
+        }
+    }
+}

docs/config/bundles.php

@@ -0,0 +1,13 @@
+<?php
+
+return [
+    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
+    ApiPlatform\Symfony\Bundle\ApiPlatformBundle::class => ['all' => true],
+    Nelmio\CorsBundle\NelmioCorsBundle::class => ['all' => true],
+    Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
+    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
+    Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
+    Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle::class => ['all' => true],
+    Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle::class => ['dev' => true, 'test' => true],
+    DAMA\DoctrineTestBundle\DAMADoctrineTestBundle::class => ['test' => true],
+];

docs/config/packages/api_platform.yaml

@@ -0,0 +1,10 @@
+api_platform:
+ formats:
+   json: [ 'application/json' ]
+   jsonld: [ 'application/ld+json' ]
+
+  # mapping:
+  #   paths:
+  #     - '%kernel.project_dir%/src'
+  # doctrine:
+  #   enabled: true

docs/config/packages/cache.yaml

@@ -0,0 +1,19 @@
+framework:
+    cache:
+        # Unique name of your app: used to compute stable namespaces for cache keys.
+        #prefix_seed: your_vendor_name/app_name
+
+        # The "app" cache stores to the filesystem by default.
+        # The data in this cache should persist between deploys.
+        # Other options include:
+
+        # Redis
+        #app: cache.adapter.redis
+        #default_redis_provider: redis://localhost
+
+        # APCu (not recommended with heavy random-write workloads as memory fragmentation can cause perf issues)
+        #app: cache.adapter.apcu
+
+        # Namespaced pools use the above "app" backend by default
+        #pools:
+            #my.dedicated.cache: null

docs/config/packages/doctrine.yaml

@@ -0,0 +1,43 @@
+doctrine:
+  dbal:
+    url: '%database_url%'
+
+    # IMPORTANT: You MUST configure your server version,
+    # either here or in the DATABASE_URL env var (see .env file)
+    #server_version: '14'
+  orm:
+    auto_generate_proxy_classes: true
+    naming_strategy: doctrine.orm.naming_strategy.underscore_number_aware
+    auto_mapping: true
+    mappings:
+      App:
+        is_bundle: false
+        dir: '%kernel.project_dir%/src'
+        prefix: 'App\Entity'
+        alias: App
+
+when@test:
+  doctrine:
+    dbal:
+      # "TEST_TOKEN" is typically set by ParaTest
+      dbname_suffix: '_test%env(default::TEST_TOKEN)%'
+
+when@prod:
+  doctrine:
+    orm:
+      auto_generate_proxy_classes: false
+      proxy_dir: '%kernel.build_dir%/doctrine/orm/Proxies'
+      query_cache_driver:
+        type: pool
+        pool: doctrine.system_cache_pool
+      result_cache_driver:
+        type: pool
+        pool: doctrine.result_cache_pool
+
+  framework:
+    cache:
+      pools:
+        doctrine.result_cache_pool:
+          adapter: cache.app
+        doctrine.system_cache_pool:
+          adapter: cache.system

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%/src'
+  enable_profiler: false

docs/config/packages/framework.yaml

@@ -0,0 +1,25 @@
+# see https://symfony.com/doc/current/reference/configuration/framework.html
+framework:
+    secret: '%env(APP_SECRET)%'
+    #csrf_protection: true
+    http_method_override: false
+    handle_all_throwables: true
+
+    # Enables session support. Note that the session will ONLY be started if you read or write from it.
+    # Remove or comment this section to explicitly disable session support.
+    session:
+        handler_id: null
+        cookie_secure: auto
+        cookie_samesite: lax
+        storage_factory_id: session.storage.factory.native
+
+    #esi: true
+    #fragments: true
+    php_errors:
+        log: true
+
+when@test:
+    framework:
+        test: true
+        session:
+            storage_factory_id: session.storage.factory.mock_file

docs/config/packages/nelmio_cors.yaml

@@ -0,0 +1,10 @@
+nelmio_cors:
+    defaults:
+        origin_regex: true
+        allow_origin: ['^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$']
+        allow_methods: ['GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']
+        allow_headers: ['Content-Type', 'Authorization']
+        expose_headers: ['Link']
+        max_age: 3600
+    paths:
+        '^/': null

docs/config/packages/routing.yaml

@@ -0,0 +1,12 @@
+framework:
+    router:
+        utf8: true
+
+        # Configure how to generate URLs in non-HTTP contexts, such as CLI commands.
+        # See https://symfony.com/doc/current/routing.html#generating-urls-in-commands
+        #default_uri: http://localhost
+
+when@prod:
+    framework:
+        router:
+            strict_requirements: null

docs/config/packages/security.yaml

@@ -0,0 +1,39 @@
+security:
+    # https://symfony.com/doc/current/security.html#registering-the-user-hashing-passwords
+    password_hashers:
+        Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface: 'auto'
+    # https://symfony.com/doc/current/security.html#loading-the-user-the-user-provider
+    providers:
+        users_in_memory: { memory: null }
+    firewalls:
+        dev:
+            pattern: ^/(_(profiler|wdt)|css|images|js)/
+            security: false
+        main:
+            lazy: true
+            provider: users_in_memory
+
+            # activate different ways to authenticate
+            # https://symfony.com/doc/current/security.html#the-firewall
+
+            # https://symfony.com/doc/current/security/impersonating_user.html
+            # switch_user: true
+
+    # Easy way to control access for large sections of your site
+    # Note: Only the *first* access control that matches will be used
+    access_control:
+        # - { path: ^/admin, roles: ROLE_ADMIN }
+        # - { path: ^/profile, roles: ROLE_USER }
+
+when@test:
+    security:
+        password_hashers:
+            # By default, password hashers are resource intensive and take time. This is
+            # important to generate secure password hashes. In tests however, secure hashes
+            # are not important, waste resources and increase test times. The following
+            # reduces the work factor to the lowest possible values.
+            Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface:
+                algorithm: auto
+                cost: 4 # Lowest possible value for bcrypt
+                time_cost: 3 # Lowest possible value for argon
+                memory_cost: 10 # Lowest possible value for argon