Symfony Advanced Resolving Laravel Package

Getting Started

• Install the package with Composer and pin the beta explicitly while 1.0.0-beta.2 is current:

  composer require vendor/package:1.0.0-beta.2
  

• Look first at:
  • README.md for the supported attribute syntax and examples.
  • src/FromQuery.php for the attribute class, its constructor options, and the new $disableTypeEnforcement static property.
  • The package tests for edge cases around type coercion, missing parameters, arrays, enums, and defaults.
• There is usually no required configuration for basic use. If the package publishes config, publish it only when you need to change global behavior.
• First use case: bind query-string values directly to typed controller arguments instead of manually reading $request->query():

  use Vendor\Package\FromQuery;
  
  public function index(
      #[FromQuery] string $search,
      #[FromQuery] int $page = 1,
      #[FromQuery] bool $active = false,
  ) {
      // $search, $page, and $active are already resolved and typed.
  }
  

• Verify with a request such as /?search=invoice&page=2&active=1. If the values arrive as strings when you expected typed values, check whether FromQuery::$disableTypeEnforcement has been set anywhere in your application or test bootstrap.

Implementation Patterns

• Use #[FromQuery] for read-only listing, filtering, and search endpoints. It keeps controllers small and makes query contracts visible in method signatures.
• Prefer a dedicated query/filter object when an endpoint has many parameters. Annotate the object rather than growing a long controller signature, and keep the object focused on query concerns.
• Rely on declared types for coercion:
  • int, float, bool for scalar filters.
  • Backed enums for finite sets such as status, sort, or type.
  • array for repeated query parameters such as ?tag[]=php&tag[]=laravel.
• Put defaults directly on parameters or properties. Missing query keys should fall back to defaults; treat required parameters as validation concerns rather than relying on the resolver.
• Integrate with Laravel validation where input rules matter. Type coercion is not validation: a query value can be coerced to an integer and still be out of range, or coerced to an enum and still be unauthorized for the current user.
• For backward compatibility with endpoints that expect raw strings, use the new global escape hatch:

  use Vendor\Package\FromQuery;
  
  // Disable type enforcement globally for this process.
  FromQuery::$disableTypeEnforcement = true;
  

  Set this in a service provider only when the whole application or a legacy subsystem needs raw query strings. Prefer narrower, per-parameter controls if the package exposes them.
• In tests, exercise both modes explicitly:

  protected function setUp(): void
  {
      parent::setUp();
      FromQuery::$disableTypeEnforcement = false;
  }
  
  protected function tearDown(): void
  {
      FromQuery::$disableTypeEnforcement = false;
      parent::tearDown();
  }
  

• Workflow tip: add feature tests for representative query strings, especially booleans, arrays, empty values, and enums. The resolver's behavior at the boundaries is where most day-to-day bugs appear.

Gotchas and Tips

• FromQuery::$disableTypeEnforcement is static global state. It affects every subsequent resolution in the same PHP process, including all requests in Octane, RoadRunner, or queue workers. Do not toggle it per request in long-running processes.
• In standard PHP-FPM the static resets per request, but in tests and long-running servers it persists. Always restore it in tearDown() or set it once during application boot.
• If typed values suddenly stop being coerced after this release, search the codebase for disableTypeEnforcement. The new property is an easy accidental global switch.
• Query strings are always strings at the HTTP boundary:
  • ?active=false may not behave like a boolean false unless the package handles it explicitly. Test both ?active=0 and ?active=false.
  • ?page= may resolve to an empty string rather than null. Normalize empty values before validation or persistence.
  • Repeated parameters arrive as arrays only with bracket syntax (tag[]=a&tag[]=b); a comma-separated value remains a string.
• Missing parameter vs. present-but-empty parameter are different cases. Confirm how the package treats ?search= and write tests for whichever behavior your endpoint requires.
• Do not treat resolved typed parameters as validated input. Run authorization and validation rules against the original request or the resolved values as appropriate.
• With a beta release, pin the exact version and read the changelog before upgrading. A static property added in 1.0.0-beta.2 may be renamed, deprecated, or replaced before stable.
• Debugging checklist:
  • Dump $request->query() to confirm the raw input.
  • Check service providers, test base classes, and middleware for FromQuery::$disableTypeEnforcement.
  • Confirm the declared parameter type matches the intended coercion.
  • Check whether the package's resolver is bypassed by a custom route binding or middleware.
• Extension point: if the package binds a resolver or type caster in the container, decorate or replace that binding rather than editing vendor code. Use FromQuery::$disableTypeEnforcement only as a last-resort global fallback, not as a substitute for proper per-endpoint handling.