Muppet Bundle Laravel Package

Getting Started

wickedOne/muppet-bundle is not a Laravel package — it is a Symfony bundle that wires the wickedOne/muppet configuration-management engine (a PHP take on Puppet: manifests, nodes, roles, tasks applied over a transport) into a Symfony container. The 2.0.0 release notes are almost entirely Dependabot bumps plus CI/tooling PRs ("setup tools", badge), so treat 2.0.0 as a maintenance major, not a feature release with a documented upgrade path.

First steps:

1. composer require wickedone/muppet-bundle (or, if Composer fights you, composer require wickedone/muppet and skip the bundle — see Gotchas).
2. Read these three things in vendor/wickedone/muppet-bundle/ before anything else:
   • composer.json — PHP floor and the Symfony component constraints, which is where 2.0.0 actually changed.
   • The *Bundle class and src/Resources/config/* — this is the service wiring you will have to reproduce by hand in Laravel.
   • The console command classes — these are the entry points you will wrap in Artisan.
3. First use case worth building: one manifest, one node, one non-production target. Define a role that ensures a directory exists, templates one config file, and installs/holds one package. Run it against staging, verify idempotency by running it twice.

Implementation Patterns

Wrap the bundle, don't expect discovery. Laravel has no bundle auto-registration. Create a MuppetServiceProvider that registers the services the bundle's services.xml/services.yaml declares, and publishes a config/muppet.php mirroring the bundle's configuration tree (node/role/manifest paths, environment, transport options).

Artisan command as the front door. Wrap the underlying command in an artisan muppet:apply command so it participates in your normal scheduling, output buffering, and --env conventions. Keep the wrapper thin — argument parsing only, no logic.

Manifests in version control, one per role. Structure as muppet/manifests/{role}.php and muppet/nodes/{env}/{node}.php, loaded from config paths rather than hardcoded. Secrets never live in manifests — read them from env()/a secrets store and inject at apply time.

Dry-run in PRs, apply on merge. This is the single highest-value workflow: run the plan/no-op mode in CI on pull requests and diff the output; only apply on merge to the main branch. Combined with idempotent manifests this gives you a poor-man's Terraform plan.

Test the manifest layer, not the transport. Fake the transport/SSH boundary and assert on the resource graph your manifest produces. Real executions belong in a staging job, not PHPUnit.

Tag custom resources. If you need your own task/resource types, register them through the container rather than instantiating inline — otherwise you inherit a hard-to-test global.

Gotchas and Tips

• The 2.0.0 changelog tells you almost nothing about breaking changes. It's dependency bumps and CI. Read the actual diff on the bundle class, the service definitions, and composer.json before upgrading. Pin the version and upgrade deliberately.
• Symfony 5.4 components vs. Laravel 9/10/11 (Symfony 6+). The dependency bumps here move many components to 5.4. If Composer refuses to resolve, the bundle is the blocker — use wickedone/muppet directly and hand-wire it. That is likely the correct long-term choice for a Laravel app anyway.
• Symfony container semantics leak. %parameter% placeholders, tagged services, and compiler passes do not exist in Laravel's container. Anything resolved through those mechanisms must be rewritten as explicit bindings.
• It executes real changes. There is no sandbox and no rollback. Always run the no-op/dry-run mode first, and gate production applies behind an explicit confirmation flag in your Artisan wrapper.
• Idempotency is your debugging tool. If a second run reports changes, the manifest is wrong — not the tool. Bisect by running a single resource at a time.
• Route output into Laravel's logger. Long apply runs interleaved with app logs are unreadable otherwise; pipe per-resource results into a structured channel with the run ID.
• Extension points to look for: custom tasks/resources, transport adapters, and any event/hook the engine dispatches between resources. Those are where you add audit logging and approval gates rather than forking.
• PHP version floor moves with the dependency bumps. Confirm your runtime matches before upgrading a working install; a silent floor increase is the most common cause of a "works locally, fails in CI" surprise with this kind of release.