Workflow

Recommended Workflow for Development & Deployment

This guide ensures consistent dependency management, safe deployments, and minimal downtime for your projects.

Avoid FTP/SFTP

Our main goal is to eliminate the use of FTP/SFTP or other file based systems for deployments because they are error-prone, slow, and insecure. Instead, we focus on Git-based deployments, automated CI/CD pipelines, and fully-managed dependencies to ensure consistency, reliability, and security across all environments. This approach reduces human errors, improves deployment speed, and ensures that every environment runs the exact same code version.

Disclaimer: This provides a structured workflow for managing dependencies. While these practices are widely recommended, they are not absolute rules. Adapt them based on your team's needs, project requirements, and infrastructure.

🛠️ 1️⃣ Local Development Workflow

This section covers how to manage dependencies.

🔹 Initial Setup (Cloning a Project)

When setting up the project for the first time:

git clone https://github.com/your-org/your-project.git
cd your-project
composer install

• This installs dependencies exactly as specified in composer.lock.
• DO NOT run composer update unless updating dependencies intentionally.

🔹 Adding a New Dependency

1. Add a package:

   composer require vendor/package-name

   • This updates both composer.json and composer.lock.

2. Commit the changes:

   git add composer.json composer.lock
   git commit -m "Added package-name"
   git push

🔹 Updating Dependencies

To check outdated packages:

composer outdated

To update a specific package:

composer update vendor/package-name

To update all dependencies:

composer update --no-dev

Then commit the updated lock file:

git add composer.json composer.lock
git commit -m "Updated dependencies"
git push

🚨 Never push an updated composer.json without the corresponding composer.lock.

🚀 2️⃣ Staging/Testing

Before deploying to production, the application should be tested with the latest dependencies.

🔹 Deploy to Staging

1. Pull the latest code:

   git pull origin main

2. Install dependencies using the composer.lock file:

   composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist --no-progress

3. Run automated/manual tests.

4. If issues occur, roll back to the last working commit.

🎯 3️⃣ Production Deployment

In production, never update dependencies directly. Always deploy tested and committed code.

🔹 Deploy to Production

1. Pull the latest tested code:

   git pull origin main

2. Install dependencies:

   composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist --no-progress

3. Clear caches (if applicable):

   rm -rf cache/*

4. Restart services if necessary:

   systemctl restart php-fpm

5. Verify that the deployment was successful.

🔄 4️⃣ Continuous Integration (CI/CD)

Automate testing and deployments using GitHub Actions, GitLab CI, or Bitbucket Pipelines.

Example GitHub Actions Workflow

name: CI/CD Pipeline

on:
  push:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Install PHP and Composer
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          tools: composer:v2

      - name: Install Dependencies
        run: composer install --no-dev --prefer-dist --no-interaction --optimize-autoloader

      - name: Run Tests
        run: php vendor/bin/phpunit

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Server
        run: |
          ssh user@your-server "cd /var/www/your-project && git pull && composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist --no-progress"

⚠️ Common Pitfalls to Avoid

• 🚫 DO NOT delete composer.lock – This leads to unpredictable dependency versions.
• 🚫 DO NOT run composer update in production – Always use composer install.
• 🚫 DO NOT commit vendor/ directory – Always use Composer to manage dependencies.

✅ Best Practices

Step	Action
🛠 Local Development	composer install (first time)
➕ Adding Packages	composer require vendor/package-name
🔄 Updating Dependencies	composer update --no-dev
🔥 Staging Deployment	composer install --no-dev --optimize-autoloader --no-interaction
🚀 Production Deployment	composer install --no-dev --optimize-autoloader --no-interaction
📜 Version Control	Always commit composer.json & composer.lock
⚡ CI/CD Pipeline	Automate testing & deployments