Df Git Laravel Package

Getting Started

dreamfactory/df-git is not a general-purpose Laravel package — it is a DreamFactory platform package that adds Git-backed version control for a DreamFactory instance's configuration (services, API definitions, roles, apps, scripts). If you are not running DreamFactory, there is nothing here for you; if you are, this is the piece that lets you treat instance config as code.

Minimal path:

1. Prereqs. A working DreamFactory install (df-core, Laravel-based), Composer access, and the git binary available to the PHP/queue user on the host (the package shells out or uses a Git library — check composer.json for gitonomy/phpgit-style deps).
2. Install into the DreamFactory project, not a standalone app:

   composer require dreamfactory/df-git
   php artisan migrate
   php artisan config:clear && php artisan cache:clear
   

   DreamFactory packages self-register via a service provider; the package should appear in the admin UI under Packages/System after install.
3. Look here first, in this order:
   • src/Providers/*ServiceProvider.php — what routes and services get registered.
   • src/Services/ — the Git service class; this is the actual surface area.
   • config/ — any repo path, branch, or credential settings.
   • php artisan route:list | grep -i git — the fastest way to see the real endpoints rather than trusting docs.
4. First use case: initialize a repo for the instance config directory, make an initial commit, add a remote, push. You now have a versioned snapshot of the whole instance that you can diff, review, and restore. That single workflow — "my DreamFactory config is in Git" — is 80% of the package's value.

Implementation Patterns

Environment promotion (dev → staging → prod). The canonical pattern: each environment runs a DreamFactory instance with df-git pointed at the same remote. Promote by branching or tagging in dev, then triggering a pull in staging/prod. Config changes become PRs instead of admin-UI clicks, which is the whole reason to adopt this.

Bootstrapped instances. Keep a repo of "golden" config and have your container entrypoint clone/pull it before the app serves traffic. This gives you reproducible DreamFactory instances and makes ephemeral CI environments trivial. Pair with a read-only token or deploy key scoped to that repo.

Pipeline integration over UI integration. Rather than clicking buttons in the admin console, call the Git endpoints from your CI (GitLab CI, GitHub Actions, Jenkins) using a system-admin API token. From a Laravel service you already own:

Http::withToken(config('services.dreamfactory.token'))
    ->post(config('services.dreamfactory.url').'/api/v2/system/git/commit', [
        'message' => "Deploy {$deployment->id}",
    ]);

Confirm exact paths and payloads from route:list and the service class — this package has effectively one maintainer and near-zero public usage, so the source is the documentation.

Scheduled snapshots. Register the commit in app/Console/Kernel.php (or a queued job) so the instance commits its own drift on a schedule. Useful as an audit trail even if humans never touch Git directly. Guard it so it's a no-op when the working tree is clean.

Treat the admin UI as an uncommitted working tree. Editors change config in the UI; the repo accumulates dirty state; a human reviews the diff and commits. This mental model prevents most surprises — especially "why did my prod config change without a commit?"

Branch-per-instance for multi-tenant or multi-region setups. Each instance owns a branch, promotion happens by merging into main/prod. Merge conflicts in exported JSON are unpleasant but visible, which beats silent divergence.

Keep secrets out. Add a .gitignore (or an export filter, if the package supports one) for .env, connection credentials, and anything the export serializes from the environment. This is the single most important configuration decision you'll make.

Gotchas and Tips

• Credential leakage is the default failure mode. DreamFactory config references database passwords, API keys, and OAuth secrets. Audit what a commit actually contains before the first push — git diff --cached on the initial import, every time, on every environment.
• It's a platform package, not a Laravel package. Expect tight coupling to the df-core version. Pin exact versions of dreamfactory/df-git and df-core together; a minor df-core bump can break the service registration.
• Adoption signals are essentially zero (1 star, 0 dependents, single-digit opportunity score). Budget for reading the source and for the possibility that a bug you hit is yours to fix. Do not put this on a critical path without a fallback (manual config export/import) documented.
• Git auth happens as the web/queue user. SSH deploy keys must exist in that user's ~/.ssh with correct known_hosts; the most common failure is a working CLI push as your shell user and a failing push from PHP. Test the exact user context.
• Conflicts on serialized JSON are the day-to-day pain. Keep commits small and frequent; avoid two people editing the same service config between pulls. If the export order is non-deterministic, diffs will be noisy — check whether the package sorts keys, and if not, consider a post-processing normalizer.
• Pulls on a dirty tree. Decide up front what happens when a pull arrives with local admin-UI changes outstanding. Either make pull refuse on dirty state (safe) or accept overwrites (dangerous). Verify the actual behavior before relying on either.
• After any config/route change: php artisan config:clear && php artisan route:list | grep -i git — stale caches are the usual cause of "the endpoints don't exist."
• Debugging: DreamFactory logs to storage/logs/laravel.log; set APP_DEBUG=true in a non-prod instance and watch that file while triggering the endpoint. For shell-out failures you often get only the exit code — reproduce the same command as the web user.
• Don't stretch it into a deploy tool. It versions DreamFactory configuration, not your application source or composer dependencies. Teams that conflate the two end up with a slow, fragile CI story.
• Extension points: the service provider and service class are the seams — subclass or decorate the Git service if you need custom export filters, commit conventions, or a different auth backend. Keeping your customization there (rather than patching the vendor dir) is what makes upgrades survivable.

Verdict for a Laravel developer: worthwhile only if you already run DreamFactory and want config-as-code with review. It's a small, single-purpose, low-traffic package — evaluate by reading ~a few hundred lines of source, not by reading docs, and pilot it on a throwaway instance before trusting it with production credentials.