Laravel Yaml Laravel Package

Getting Started

This package is a thin Laravel service provider that teaches the framework to read config/*.yaml / *.yml files alongside the usual PHP files. It was last released in March 2016 (Laravel 5.1/5.2 era), is archived, and has essentially zero adoption — treat it as a reference implementation you may vendor/fork rather than a dependency you install and forget.

Minimal path to a working setup:

1. Install with a pinned constraint. Because it is archived, Composer will still resolve the 2016 tag, but you must pin it explicitly and make sure its Symfony YAML requirement is compatible with your framework:

   composer require theofidry/laravel-yaml:^0.1
   

2. Register the provider in config/app.php under providers (it predates package auto-discovery):

   TheoFidry\LaravelYaml\LaravelYamlServiceProvider::class,
   

3. Drop a YAML file in config/ next to your PHP files and confirm it is picked up:

   # config/services.yaml
   mailgun:
     domain: mg.example.com
     endpoint: api.mailgun.net
   

   config('services.mailgun.domain');
   

4. Where to look first — open the provider's register()/boot() and find where it hooks into configuration loading. That one method (plus the Symfony Yaml::parse call inside it) is the entire package; reading it takes minutes and tells you exactly what merge order and parser flags you are getting.
5. First real use case: moving large, mostly-static config blocks (feature flags, third-party service matrices, queue/topology maps) out of deeply nested PHP arrays into readable YAML, while leaving environment-sensitive values in PHP or .env.

Implementation Patterns

One file per top-level config key. Mirror Laravel's convention so YAML and PHP files compose predictably: config/services.yaml maps to config('services.*'), config/features.yaml to config('features.*'). Avoid mixing YAML and PHP for the same top-level key unless you have confirmed the provider's merge order — collisions are the most common source of "my value isn't there" bugs.

Layer YAML underneath PHP for overrides. The durable pattern is: YAML holds the big static defaults, PHP holds the environment-specific overrides that read env(). Since YAML cannot call PHP helpers, keeping env() dependencies in the PHP layer is not optional — it is the only way to get environment awareness.

Environment overlays done by hand. There is no built-in app.production.yaml cascading in a package this small. If you need environment-specific YAML, load the base file in your own provider and array_replace_recursive the overlay before the framework caches config:

$base    = Yaml::parseFile(config_path('features.yaml'));
$overlay = Yaml::parseFile(config_path('features.'.app()->environment().'.yaml'));
config(['features' => array_replace_recursive($base, $overlay)]);

Package configuration. For your own packages, ship a config/*.yaml default and merge it in the package provider using mergeConfigFrom against the parsed array — the same pattern as PHP, just with the YAML parser as the source.

Consume through config() only. Never parse YAML at runtime inside application code. Parse once at boot (or let the provider do it), then read through config(). This keeps a single caching boundary and makes it trivial to rip the package out later — you replace the loader, not every call site.

Cache aggressively, but verify. php artisan config:cache will serialize whatever ends up in the config repository, so YAML is flattened into the cached PHP array and the parser is not invoked in production. That is the intended production workflow: parse at deploy time, cache, serve.

Gotchas and Tips

• It is archived and unmaintained. No Laravel 6+ support, no PHP 8 guarantees. On any modern Laravel the LoadConfiguration bootstrapper has changed enough that the provider's hook may simply never fire. Budget for forking it or replacing it — the package is a few hundred lines, so reimplementing is usually cheaper than debugging it.
• Symfony YAML version conflicts. Depending on the tag, it pulls Symfony YAML 2.x/3.x. Modern Laravel ships Symfony 5/6/7 components; you will hit constraint conflicts. Aliasing or a replace in composer.json is the workaround, but then you are testing the old parsing code against a new parser API.
• env() does not exist in YAML. Strings like ${APP_URL} are not interpolated unless the loader implements Yaml::PARSE_.../custom tag handling. Either preprocess the raw text with strtr/preg_replace_callback before parsing, or keep env-dependent values out of YAML entirely.
• YAML type coercion will bite you. yes/no/on/off become booleans under YAML 1.1 rules, unquoted dates become timestamps, and 0123 may parse as octal. Quote anything that must remain a string: version: "1.10", port: "8080".
• Tabs are illegal for indentation. A single tab produces a ParseException with a line number but no column — the most common YAML debugging session. Configure your editor to expand tabs in *.yaml.
• Parser flags matter for security and fidelity. Prefer Yaml::parseFile($path, Yaml::PARSE_CONSTANT) style calls with an explicit flag set. Do not enable object deserialization for config files; there is no reason for config to instantiate PHP objects.
• config:cache masks problems. Because the cache short-circuits parsing, a broken YAML file will pass CI and only explode on an uncached deploy or in local dev. Add a test or a deploy step that runs php artisan config:clear && php artisan config:cache to exercise the parser every build.
• Debugging checklist: php artisan tinker → config('your.key'); dd(config()->all()) for a full dump; php artisan config:clear before concluding anything is broken. If a key is missing, check whether a PHP file with the same top-level key overwrote the YAML merge.
• Extension points are limited but real. The parser call is the seam: subclass the provider (or write your own ten-line provider) to swap in a stricter parser, add env interpolation, or add environment overlays. That is the practical migration path off the package — keep the YAML files, replace the loader.