Idcard Manage Bundle Laravel Package

Getting Started

Treat 0.1.0 as an early, pre-1.0 release. The release notes only link to a changelog, so inspect the package source before adopting it. The package name tourze/idcard-manage-bundle and the -bundle suffix strongly suggest a Symfony bundle rather than a native Laravel package; do not expect Laravel package discovery, publishable config, migrations, facades, or a Laravel service provider.

Minimal steps:

1. Check compatibility before installing:

   composer require --dry-run tourze/idcard-manage-bundle:^0.1
   

2. Inspect vendor/tourze/idcard-manage-bundle/composer.json, the README, service definitions, and tests. Look for framework-agnostic ID-card services you can call from Laravel.
3. If the package depends heavily on Symfony DI/configuration, do not wire the bundle directly into a Laravel app. Either isolate it behind an adapter or use only its standalone domain classes.
4. Start with a narrow use case: validate or normalize an ID-card number in a form request, import command, or API request.

The first practical integration is usually a small Laravel adapter service that wraps the package’s parser/validator/manager and exposes a stable application-level API.

Implementation Patterns

Use an adapter boundary rather than calling bundle classes throughout your Laravel codebase:

final class IdCardService
{
    public function normalize(string $value): string
    {
        // Delegate to the package service here.
    }

    public function isValid(string $value): bool
    {
        // Delegate to the package validator here.
    }
}

Bind it in a service provider and inject the interface into controllers, form requests, jobs, and commands. This keeps Symfony-specific details out of your Laravel domain code.

Common patterns:

• Validation rule: Create a custom Laravel validation rule that calls your adapter. Do not invoke package internals directly from controllers.
• Import pipeline: Validate and normalize ID cards in chunked jobs/commands, record failures without logging raw ID-card values, and keep PII out of application logs.
• Configuration: If the bundle expects Symfony parameters, map those values into a Laravel config/idcard.php file. Avoid depending on Symfony container parameters at runtime.
• Testing: Write contract tests around your adapter using known-valid and known-invalid fixtures. Assert exception behavior and normalization output, not internal bundle classes.
• Upgrades: Pin the version initially, read the compare link for 0.0.3...0.1.0, and rerun adapter tests before widening the constraint.

If the package exposes only Symfony bundle wiring, consider keeping it in a separate Symfony service or extracting the ID-card logic you need. Do not make your Laravel application depend on Symfony bundle bootstrapping unless you have verified that path in a spike.

Gotchas and Tips

• Empty release notes: 0.1.0 only provides a changelog link. Under semver, 0.x minor releases may still include breaking changes. Pin an exact version or ^0.1 only after inspecting the diff.
• Not Laravel-native: The package is unlikely to support Laravel auto-discovery, vendor:publish, Laravel config caching, or Laravel’s container conventions. Expect manual integration.
• Container differences: Symfony service tags, parameter bags, event dispatchers, and autowiring behavior do not map one-to-one to Laravel. Verify every service you resolve with app()->make().
• Avoid editing vendor code: If configuration or wiring is missing, create a Laravel-side adapter or bridge instead of patching vendor/.
• PII handling: ID-card data is sensitive. Mask values in logs, avoid storing raw numbers unnecessarily, and be careful with failed-job payloads.
• Jurisdiction assumptions: ID-card validation rules are region-specific. Confirm the package’s expected format and checksum behavior before relying on it.
• Debugging: Use composer why tourze/idcard-manage-bundle, inspect composer.json platform requirements, and run the package’s own tests if available. Container resolution failures usually indicate missing Symfony wiring rather than a Laravel bug.
• Extension points: Prefer wrapping public services/interfaces. Avoid extending internal bundle classes, since pre-1.0 releases are likely to reorganize namespaces and service IDs.