Laraupdater Laravel Package

Getting Started

• Install with Composer and confirm the runtime first: composer require pcinaglia/laraupdater requires PHP 7.4/8.x, a Laravel version inside the package's (dated) constraint, and the zip extension enabled. Check composer show pcinaglia/laraupdater before assuming Laravel 10/11 support.
• Publish the config and read it end to end — this is the package's entire control surface:

  php artisan vendor:publish --provider="Pcinaglia\LaraUpdater\LaraUpdaterServiceProvider"
  

  Pay attention to: the temp/upload directory, backup directory, version file name, the allow_users list, route prefix/middleware, and the commands array executed after extraction.
• Put a version file (or configured equivalent) in the project root and keep it in sync with version_installed in the config. The updater compares this against the version file inside the uploaded archive; if the archive's version file isn't at the ZIP root, the update is rejected or misdetected.
• Make the app root writable by the PHP-FPM/web user. LaraUpdater extracts directly over the live codebase — there is no release directory. Verify ownership before your first run, and make sure the backup/temp folders are writable and outside the webroot (or blocked by nginx/Apache).
• First use case: sign in as one of the allow_users IDs, visit the configured route (default /laraupdater), upload a ZIP of the new release, and click update. Confirm the version changed, the post-update commands ran, and the backup exists. Do this on a staging clone of production, never on production first.

Implementation Patterns

• Treat the ZIP as a build artifact, not a git archive. Build it in CI: compiled frontend assets, vendor/ if you aren't running Composer on the server, application code, and the bumped version file. Explicitly exclude .git, node_modules, tests, .env, storage/, and local logs. The extractor overwrites whatever is in the archive, so anything shipped is deployed.
• Version discipline. Use semver in the version file and bump it in the release commit/CI step. Trim whitespace — a trailing newline is a common cause of "no update available" or a false positive. Use version_compare semantics rather than string equality if you customize anything.
• Chain the real deploy steps in commands. Typical array:

  'commands' => [
      'php artisan migrate --force',
      'php artisan config:cache',
      'php artisan route:cache',
      'php artisan view:cache',
      'php artisan queue:restart',
      'php artisan up',
  ],
  

  Add a tiny custom Artisan command that calls opcache_reset() (or restarts PHP-FPM) because the updater cannot invalidate OPcache itself.
• Wrap it for automation. For CI-driven deploys, have your pipeline scp the ZIP into the temp folder and invoke the update through an Artisan command or the package's service/facade instead of the web form. Keep the HTTP route for manual recovery only.
• Auth hardening. Put the route behind your normal session auth plus an IP allowlist or VPN. allow_users is a coarse gate; combine it with middleware and force HTTPS. Consider disabling the routes entirely in local/staging via config.
• Maintenance mode around the update. php artisan down before extracting, php artisan up in the post-commands. This prevents requests hitting half-extracted PHP files.
• Backup retention. Schedule pruning of the backup folder (e.g., Storage::deleteDirectory older than N days). Backups accumulate at every release and will fill the disk.
• Storage and .env are out of band. Keep them out of the archive and ensure php artisan storage:link isn't needed again unless the symlink was overwritten.

Gotchas and Tips

• OPcache will lie to you. Files change on disk, but PHP-FPM serves cached opcodes. Without an opcache reset or FPM reload, users see the old code and you'll debug a "deployed but not deployed" ghost.
• Cached config silently overrides the config file. If config:cache was run, edits to laraupdater.php (allow users, commands, paths) do nothing until config:clear. This is the most common "the package is broken" report.
• No rollback button. Backups exist, but restoring is manual: stop the app, copy the backup back, restore the DB if migrations ran. Migrations are not transactional across engines. Test destructive migrations on staging.
• Permissions drift. Extraction as www-data can leave files owned by the web user while your deploy user/git expects otherwise. Files also lose executable bits from the ZIP, so scripts and binaries can break.
• Upload and execution limits. Large ZIPs hit upload_max_filesize, post_max_size, max_execution_time, and memory_limit. Watch the server logs on the first real release.
• ZIP layout matters. A single wrapping folder (myapp-v1.2.3/...) causes files to land in a subdirectory instead of the app root. Keep version and artisan at the archive root.
• The update route is effectively remote code execution if auth or allow_users is misconfigured, and it's a tempting target on a public host. Audit middleware after every config change; block the path at the reverse proxy as defense in depth.
• Never ship .env or storage/. Overwriting .env with a stale local copy is a classic outage; it's not backed up unless you put it there.
• Multi-server and containers are out. The package updates the local filesystem of one host. Immutable containers, read-only filesystems, load-balanced fleets, and horizontally scaled apps need a real deploy tool (Envoyer, Deployer, GitHub Actions + SSH).
• Package maturity risk. Last release February 2023 and near-zero dependents means Laravel compatibility and security fixes are on you. Pin the version, read the source (it's small), and be prepared to fork or vendor the update service if you depend on it. For most teams the honest answer is: use this for a small single-VPS app with no CI/CD, and migrate to a standard pipeline as soon as you can.