PHPackages schmunk42/api-platform-utils-bundle - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Database & ORM](/categories/database) 4. / 5. schmunk42/api-platform-utils-bundle ActiveSymfony-bundle[Database & ORM](/categories/database) schmunk42/api-platform-utils-bundle =================================== Generic utilities for API Platform projects: UUID resolver, credential encryption, OpenAPI enhancements, and Hydra operations 0.1.0(5mo ago)02MITPHPPHP >=8.2 Since Nov 23Pushed 5mo agoCompare [ Source](https://github.com/schmunk42/api-platform-utils-bundle)[ Packagist](https://packagist.org/packages/schmunk42/api-platform-utils-bundle)[ RSS](/packages/schmunk42-api-platform-utils-bundle/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (9)Versions (2)Used By (0) schmunk42 API Platform Utils Bundle =================================== [](#schmunk42-api-platform-utils-bundle) Generic utilities for API Platform projects: UUID resolver, credential encryption, OpenAPI enhancements, and Hydra operations. Features -------- [](#features) - **UUID Resolver**: Find entities by full or partial UUID (supports both binary and string UUID storage) - **Credential Encryption**: Secure encryption/decryption using libsodium (XChaCha20-Poly1305) - **Relation Field Schema Decorator**: Automatically adds x-\* metadata to OpenAPI schemas for admin UI autocomplete - **Hydra Operations Subscriber**: Enriches JSON-LD responses with operation metadata for better API discoverability Installation ------------ [](#installation) ### 1. Add to composer.json [](#1-add-to-composerjson) Since this is an internal bundle in the `extensions/` directory, add autoloading: ``` { "autoload": { "psr-4": { "Schmunk42\\ApiPlatformUtils\\": "extensions/api-platform-utils-bundle/src/" } } } ``` Run composer dump-autoload: ``` composer dump-autoload ``` ### 2. Register Bundle [](#2-register-bundle) Add to `config/bundles.php`: ``` return [ // ... Schmunk42\ApiPlatformUtils\Schmunk42ApiPlatformUtilsBundle::class => ['all' => true], ]; ``` ### 3. Configure [](#3-configure) Create `config/packages/schmunk42_api_platform_utils.yaml`: ``` schmunk42_api_platform_utils: # Credential Encryption (required) credential_encryption: key: '%env(base64:CREDENTIALS_ENCRYPTION_KEY)%' # Relation Field Schema Decorator (optional) relation_field_decorator: api_prefix: '/api' decoration_priority: 10 label_property_candidates: - name - title - label - displayName # Hydra Operations (optional) hydra_operations: api_prefix: '/api' event_priority: -10 ``` ### 4. Set Environment Variable [](#4-set-environment-variable) Add to `.env`: ``` # Generate with: docker compose exec php bin/console app:generate-encryption-key CREDENTIALS_ENCRYPTION_KEY="base64-encoded-32-byte-key-here" ``` Usage ----- [](#usage) ### 1. UUID Resolver [](#1-uuid-resolver) Find entities by full or partial UUID: ``` use Schmunk42\ApiPlatformUtils\Service\UuidResolver; class MyCommand extends Command { public function __construct( private readonly UuidResolver $uuidResolver ) { parent::__construct(); } protected function execute(InputInterface $input, OutputInterface $output): int { // Find by full UUID $entity = $this->uuidResolver->findByPartialUuid( Project::class, '550e8400-e29b-41d4-a716-446655440000' ); // Find by partial UUID (first 8 characters) $entity = $this->uuidResolver->findByPartialUuid( Project::class, '550e8400' ); if ($entity === null) { $output->writeln('Entity not found'); return Command::FAILURE; } return Command::SUCCESS; } } ``` **Features**: - Supports binary UUID storage (BINARY(16) with Symfony Uid) - Supports string UUID storage (CHAR(36) / GUID) - Throws exception if partial UUID is ambiguous - Automatically detects storage type from Doctrine metadata ### 2. Credential Encryption [](#2-credential-encryption) Securely encrypt/decrypt API credentials: ``` use Schmunk42\ApiPlatformUtils\Service\CredentialEncryption; class MyService { public function __construct( private readonly CredentialEncryption $encryption ) {} public function store(array $credentials): string { // Encrypt credentials return $this->encryption->encrypt([ 'username' => 'user@example.com', 'password' => 'secret123', 'api_token' => 'token_abc123' ]); } public function retrieve(string $encryptedData): array { // Decrypt credentials try { return $this->encryption->decrypt($encryptedData); } catch (\RuntimeException $e) { // Decryption failed return []; } } } ``` **Generate Encryption Key**: ``` use Schmunk42\ApiPlatformUtils\Service\CredentialEncryption; // Generate a new base64-encoded 32-byte key $key = CredentialEncryption::generateKey(); echo "CREDENTIALS_ENCRYPTION_KEY=" . $key; ``` **Security Features**: - Uses PHP's built-in libsodium (XChaCha20-Poly1305) - Automatic nonce generation - Memory cleanup with sodium\_memzero - Base64 encoding for storage ### 3. Relation Field Schema Decorator [](#3-relation-field-schema-decorator) Automatically enhances OpenAPI schemas for Doctrine relations. **No code required!** **Example Entity**: ``` use ApiPlatform\Metadata\ApiResource; use Doctrine\ORM\Mapping as ORM; #[ORM\Entity] #[ApiResource] class Project { #[ORM\ManyToOne(targetEntity: Customer::class)] private ?Customer $customer = null; } ``` **Generated OpenAPI Schema**: ``` { "Project": { "properties": { "customer": { "type": ["string", "null"], "format": "iri-reference", "x-collection": "/api/admin/customers", "x-label-property": "name", "x-value-property": "@id", "x-search-property": "name", "x-resource-class": "Customer" } } } } ``` **What it does**: - Detects all Doctrine relations (ManyToOne, OneToOne, ManyToMany) - Adds x-collection URL for autocomplete endpoints - Infers label property from entity (checks: name, title, label, displayName) - Only applies to INPUT schemas (forms, not responses) - Configurable API prefix and label property candidates **Use in Admin UI**: The x-\* extensions are used by admin UIs (like API Platform Admin) to render autocomplete dropdowns for relation fields. ### 4. Hydra Operations Subscriber [](#4-hydra-operations-subscriber) Automatically adds operation metadata to JSON-LD item responses. **No code required!** **Before** (Standard JSON-LD response): ``` { "@id": "/api/admin/projects/550e8400", "@type": "Project", "name": "My Project" } ``` **After** (With hydra:operation): ``` { "@id": "/api/admin/projects/550e8400", "@type": "Project", "name": "My Project", "hydra:operation": [ { "@id": "/api/admin/projects/550e8400", "@type": "hydra:Operation", "method": "GET", "title": "Retrieves a Project resource", "returns": "Project" }, { "@id": "/api/admin/projects/550e8400", "@type": "hydra:Operation", "method": "PUT", "title": "Replaces the Project resource", "expects": "Project", "returns": "Project" }, { "@id": "/api/admin/projects/550e8400/health", "@type": "hydra:Operation", "method": "GET", "title": "Health", "returns": "Project" } ] } ``` **What it does**: - Adds complete list of available operations to each item response - Includes standard CRUD operations and custom operations - Generates human-readable titles for operations - Adds expects/returns schema information - Makes API self-documenting and discoverable Configuration Reference ----------------------- [](#configuration-reference) ``` schmunk42_api_platform_utils: credential_encryption: enabled: true # Enable/disable credential encryption service key: '%env(base64:CREDENTIALS_ENCRYPTION_KEY)%' # Required: 32-byte base64-encoded key relation_field_decorator: enabled: true # Enable/disable OpenAPI decorator api_prefix: '/api' # API prefix for collection paths decoration_priority: 10 # Decorator priority (higher = runs first) label_property_candidates: # Property names to check for labels (in order) - name - title - label - displayName hydra_operations: enabled: true # Enable/disable Hydra operations subscriber api_prefix: '/api' # API prefix for operation paths event_priority: -10 # Event priority (negative = after API Platform) ``` Requirements ------------ [](#requirements) - PHP 8.2+ - ext-sodium (built into PHP 7.2+) - Symfony 7.0+ - API Platform 3.0+ - Doctrine ORM 2.0+ / 3.0+ Architecture ------------ [](#architecture) ### Bundle Structure [](#bundle-structure) ``` api-platform-utils-bundle/ ├── src/ │ ├── Schmunk42ApiPlatformUtilsBundle.php # Main bundle class │ ├── DependencyInjection/ │ │ ├── Configuration.php # Configuration tree │ │ └── Schmunk42ApiPlatformUtilsExtension.php # DI extension │ ├── Service/ │ │ ├── UuidResolver.php # UUID resolver service │ │ └── CredentialEncryption.php # Encryption service │ ├── OpenApi/ │ │ └── RelationFieldSchemaDecorator.php # OpenAPI decorator │ └── EventSubscriber/ │ └── AddHydraOperationsSubscriber.php # Event subscriber ├── config/ │ └── services.yaml # Service definitions ├── composer.json ├── README.md └── CHANGELOG.md ``` ### How It Works [](#how-it-works) 1. **UuidResolver**: Uses Doctrine metadata to detect UUID storage type (binary vs string), then performs partial matching via SQL LIKE queries 2. **CredentialEncryption**: Wraps PHP's libsodium crypto\_secretbox functions for symmetric encryption with automatic nonce handling 3. **RelationFieldSchemaDecorator**: Decorates API Platform's SchemaFactory, processes INPUT schemas, detects Doctrine associations, and adds x-\* extensions 4. **AddHydraOperationsSubscriber**: Listens to ResponseEvent, checks for JSON-LD item responses, extracts all operations from resource metadata, and enriches response License ------- [](#license) Proprietary - herzog kommunikation GmbH Credits ------- [](#credits) Developed for the ZA7 (Zentrales Agentursystem Version 7) project. ### Health Score 30 — LowBetter than 64% of packages Maintenance70 Regular maintenance activity Popularity2 Limited adoption so far Community6 Small or concentrated contributor base Maturity37 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 176d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/3b4ab2b6685ec71887908ec8cff261a16cd5bb24c69bb8ab52840e220f175f9d?d=identicon)[schmunk](/maintainers/schmunk) --- Top Contributors [![schmunk42](https://avatars.githubusercontent.com/u/649031?v=4)](https://github.com/schmunk42 "schmunk42 (3 commits)") --- Tags symfonyencryptionopenapidoctrineuuidHydrautilitiesapi-platform ### Embed Badge ![Health badge](/badges/schmunk42-api-platform-utils-bundle/health.svg) ``` [![Health](https://phpackages.com/badges/schmunk42-api-platform-utils-bundle/health.svg)](https://phpackages.com/packages/schmunk42-api-platform-utils-bundle) ``` ### Alternatives [sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.4k5.6M651](/packages/sylius-sylius)[sulu/sulu Core framework that implements the functionality of the Sulu content management system 1.3k1.3M152](/packages/sulu-sulu)[contao/core-bundle Contao Open Source CMS 1231.6M2.4k](/packages/contao-core-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)