How to create CakePHP project (previous version) using Composer (using an old version of PHP, in 2023)

Question

TL;DR Technology moving on and what was deprecated is obsolete now. But fear not, Docker here to solve the problem. See the answer below to see how I create a CakePHP 3.6 project on macOS Ventura.

---

Here, in 2023, I have my Mac updated to Ventura (13.0.1) with brew installed (Homebrew 3.6.18) and I have this requirement to create a CakePHP project, specifically version 3.6 (I am very well aware of CakePHP 3.x End of Support - but life happens). Now the scene was set, let's go and rock-and-roll!
Heading to installation documentation yields these;

1. Install PHP - per documentation PHP 7.4 is supported, yay (sort of)
2. Install Composer - there is at least one another alternative, the Oven way, but I haven't tried it
3. Create a CakePHP Project

OK, let me install PHP. Oh, I already PHP installed via brew, PHP 8.2.1. Good then let me check if I already have Composer installed as well, composer --version; yes "Composer version 2.4.4 2022-10-27 14:39:29". So the last thing I need to do is to Create a CakePHP Project. Let me run composer create-project --prefer-dist cakephp/app:"^3.6" my_app_name;

Creating a "cakephp/app:^3.6" project at "./my_app_name"
Info from https://repo.packagist.org: #StandWithUkraine
Installing cakephp/app (3.10.1)
  - Installing cakephp/app (3.10.1): Extracting archive
Created project in /Users/johndoe/Code/my_app_name
Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - cakephp/cakephp[3.10.0, ..., 3.10.5] require php >=5.6.0,<8.0.0 -> your php version (8.2.1) does not satisfy that requirement.
    - Root composer.json requires cakephp/cakephp 3.10.* -> satisfiable by cakephp/cakephp[3.10.0, ..., 3.10.5].

Oh, noes . Well, let me downgrade my PHP version, or better yet let brew install PHP 7.4 side-by-side (actually it was not a "better yet"). Quick Googling yield Update PHP to 7.4 macOS Catalina with brew on SO. Hmm, I'm on Venture and this is for Catalina. But there is one comment;

This solution works perfectly in MacOS BigSur.

-juanitourquiza

I took juanitourquiza's word for it, besides there's nothing to lose... Except for those irritating "libicuio.71.dylib no such file" errors. It turned out that "Xcode 7.1 changed the name of some libraries now it uses .tdb files.". Bummer!

There I was scratching my head, I thought to myself "well I'm already going to use Docker to serve the app anyway (locally), why not use Docker to create the project too?".

Answer 1

First and foremost you have to have Docker installed, and how is another story.

Create a CakePHP Project - Take 2

Next this little command would suffice to create a CakePHP 3.6 project;

docker run -it --rm \
    --name php74_composer \
    -v "$PWD":/usr/src/myapp \
    -w /usr/src/myapp \
    php:7.4-cli sh -c "pwd; apt-get update && apt-get install -y unzip; \
        curl https://raw.githubusercontent.com/composer/getcomposer.org/76a7060ccb93902cd7576b67264ad91c8a2700e2/web/installer | php; \
        php composer.phar create-project --no-install --no-interaction --no-scripts --prefer-dist cakephp/app:\"3.6.5\" my_app_name; \
        cd my_app_name; \
        php ../composer.phar config --no-plugins allow-plugins.cakephp/plugin-installer true; \
        php ../composer.phar install --ignore-platform-reqs; \
        php ../composer.phar run --no-interaction post-install-cmd; \
        cd ../ && rm composer.phar; \
        exit"

Although it's highly opinionated about the versions (PHP 7.4 and CakePHP 3.6.5) it does the trick! When you run it, it'll create a directory called "my_app_name" on the current working directory. After the container exit out you may move this directory anywhere as your heart desire.

Serve the App

As I mentioned I am going to use Docker as well to serve the app (locally). There are trillion tutorials out there showing how to do it, nonetheless here's my solution;

# In the "my_app_name" directory

mkdir docker && cd docker

echo "FROM php:7.4-fpm

RUN apt-get update && apt-get install -y \\
    libicu-dev \\
    git \\
    curl \\
    zip \\
    unzip

RUN docker-php-ext-configure intl
RUN docker-php-ext-install intl
RUN docker-php-ext-enable intl

RUN docker-php-ext-configure pdo_mysql
RUN docker-php-ext-install pdo_mysql
RUN docker-php-ext-enable pdo_mysql

RUN curl https://raw.githubusercontent.com/composer/getcomposer.org/76a7060ccb93902cd7576b67264ad91c8a2700e2/web/installer | php && \\
    mv composer.phar /usr/local/bin/composer

WORKDIR /var/www" > Dockerfile

echo "version: '3.8'

services:
  app:
    build:
      context: ./
      dockerfile: Dockerfile
    container_name: johndoes-app
    restart: always
    working_dir: /var/www
    volumes:
      - ../:/var/www

  nginx:
    image: nginx:1.23-alpine
    container_name: johndoes-nginx
    restart: always
    ports:
      - 8000:80
    volumes:
      - ../:/var/www
      - ./nginx:/etc/nginx/conf.d
" > docker-compose.yml

mkdir nginx && cd nginx

echo "server {
    listen 80;
    index index.php;
    error_log /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;
    error_page 404 /index.php;
    root /var/www/webroot;
    location ~ \.php {
        try_files \$uri =404;
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME \$document_root\$fastcgi_script_name;
    }
    location / {
        try_files \$uri \$uri/ /index.php?\$query_string;
    }
}
" > nginx.conf

And then at "my_app_name/docker" run docker-compose up. After services started go to "http://localhost:8000".

Now you may proceed with configuring your app. Cheers.

---

Update for Xdebug

If you wish to debug your app via VSCode / VSCodium running on your host machine (Mac in my case);

1. Append the following to Dockerfile (in between existing lines denoted);

   # existing RUN docker-php-ext-enable pdo_mysql
   
   RUN pecl install xdebug-3.1.6 && docker-php-ext-enable xdebug
   
   # existing RUN curl https://raw.githubusercontent.com/composer/getcomposer.org/...
   

2. Append the following to docker-compose.yml (in between existing lines denoted);

   # for "app" service
   # existing - ../:/var/www
   - ./99-xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
   # mind indentation since this is a YAML file, i.e.;
   # dashes must be on the same level vertically
   

3. Create the INI file for Xdebug;

   # at the docker directory
   echo "zend_extension = xdebug
   xdebug.mode = debug
   xdebug.start_with_request = yes
   xdebug.client_host = host.docker.internal" > 99-xdebug.ini
   

4. Install the PHP Debug extension for VSCode or for VSCodium.

5. As the final step have a .vscode/launch.json file including these;

   {
     "name": "Listen for Xdebug",
     "type": "php",
     "request": "launch",
     "port": 9003,
     "pathMappings": {
       "/var/www": "${workspaceFolder}"
     }
   }
   

   "pathMappings" is the crucial setting here, others were automatically generated.