MacOS

Table of contents

  1. Overview
  2. Install Homebrew
  3. Node.js
  4. Development Setup
  5. XAMPP


1. Overview Table of Contents

This guide shows you how to setup this framework on MacOS.

2. Install Homebrew Table of Contents

  • A. If not already installed, setup Homebrew using the command below: 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  • B. Apple Silicon Extra Steps
    • Ensure you run the 3 commands required after the setup process is finished to setup your path.

3. Node.js Table of Contents

1: Option 1 - Install via Homebrew (Recommended)

  • A. Run: 
    brew install node

2: Option 2: Install via NVM (Node Version Manager)

This allows you to manage multiple Node.js versions.

  • A. Install NVM 
    brew install nvm
  • B. Setup NVM
    • Add the following to your ~/.zshrc (or ~/.bashrc if using Bash): 
      export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && . "/opt/homebrew/opt/nvm/nvm.sh"
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion" ] && . "/opt/homebrew/opt/nvm/etc/bash_completion"
    • Reload shell configuration: 
      source ~/.zshrc
  • C. Install Node.js using NVM 
    nvm install --lts
  • D. Verify installation
    • Run 
      node -v
npm -v
    • Expected output: 
      vXX.XX.X (Node.js version)
X.X.X (NPM version)


4. Development Setup Table of Contents

1: PHP Setup

  • A. Install PHP
    • Run: 
      brew install php
  • B. Verify install
    • Run: 
      php -v

  • C: Configure PHP

    Apple Silicon:

      sudo vi /opt/homebrew/etc/php/8.4/php.ini

    Intel:

      /usr/local/etc/php/8.4/php.ini

    Then modify the following settings:

    Setting What it controls Safe recommended value
    upload_max_filesize Max size of a single uploaded file 5M (or 10M if high-res image uploads)
    post_max_size Max size of total POST body (form fields + files) 8M (or 15M if upload_max_filesize is 10M)
    max_execution_time Max script run time (seconds) 30 to 60
    memory_limit Max memory a script can use 128M (or 256M for image-heavy apps)

    These value should be set depending on what type of files being uploaded. Files such as videos should be much higher. post_max_size should be greater than upload_max_filesize. Otherwise, you will get a corrupted token error instead.

  • D: Start PHP as a service
    • Run: 
      brew services start php

2: Setup Composer

  • A. Run: 
    brew install composer
  • B. Verify install. Run: 
    composer -v

3: Setup and Run Project

  • A. Run the command (replace my-app with the name of your project): 
    composer create-project chappy-php/chappy-php my-app
  • B. Open the project with your preferred IDE. We use VScode.
  • C. In the terminal run the command: 
    php console serve
  • D. In a new terminal tab run the command: 
    npm run dev
  • E. Navigate to localhost:8000 in your preferred web browser.

5. XAMPP Table of Contents

Things to consider

  • When using XAMPP you should install XAMPP first before setting up composer.
  • By default, XAMPP stores all web files in /Applications/XAMPP/htdocs/.
  • We recommend moving htdocs outside /Applications/XAMPP/ to avoid losing files when upgrading XAMPP.
  • For example, you can move it to ~/Sites/htdocs/ and update Apache’s config.
  • Updates to composer packages may require you to upgrade XAMPP.

1: Setup

  • A. Open browser and go to https://www.apachefriends.org/ and download XAMPP for MacOS.
  • B. Run installer using default options.

2: Setup Composer

  • A. Install Composer.
    • Run: 
      brew install composer
    • Verify install. Run: 
      composer -v

3: Project Setup

  • A. Navigate to Applications/XAMPP/htdocs or your alternate location for htdocs using the Terminal.
  • B. Run the command (replace my-app with the name of your project): 
    composer create-project chappy-php/chappy-php my-app
  • C. Open manager-osx.
  • D. Within the manager-osx start all services.
  • E. Open project in your preferred editor. We use VSCode.
  • F. Open the .env file.
  • G. Set APP_DOMAIN TO http://localhost/chappy-php/. If you renamed your project directory then the second portion of the URL must match. The URL must have the last forward slash. Otherwise, the page and routing will not work correctly.
  • H. Update the database section: 
    # Set to mysql or mariadb for production
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
# Set to your database name for production
DB_DATABASE=chappy
DB_USER=root
DB_PASSWORD=    # Sometimes uses root as password
  • I. Run the command: ```sh npm run dev
* J. Open browser and navigate to `http://localhost/chappy-php/home`.
<br>

#### 4: Ensure XAMPP Starts on Boot
To ensure XAMPP services start automatically, open Terminal and run:
```sh
sudo launchctl load -w /Library/LaunchDaemons/org.apache.httpd.plist
sudo launchctl load -w /Library/LaunchDaemons/org.mysql.mysqld.plist

5: Moving XAMPP’s Root Directory (htdocs)

By default, XAMPP’s htdocs directory is located inside /Applications/XAMPP/htdocs. However, for easier management and to prevent data loss when updating XAMPP, it’s recommended to move it to another location.

Watch this video tutorial to learn how to move the root directory properly:

📺 How to Change XAMPP Root Directory on MacOS YouTube