Sugar Development on macOS

I am going to review one possible method to set up macOS for Sugar development, this is my preferred setup. I have chosen not to leverage Vagrant, VirtualBox, Docker, or other virtual machines. I develop using this configuration because I can be working on as many as 15 different clients' Sugar customizations in addition to Sugar Add-Ons such as Sugar Messaging, Sugar Slack, Sugar Google Address Lookup, and Sugar Mapping. This configuration affords me the flexibility to quickly switch between instances as well as give access to testers.

My toolbox is filled with a variety of different tools including HomeBrew, PhpStorm, BBEdit, phpMyAdmin, ngrok, Postman, as well as a number of homegrown command-line tools that we will discuss in a future blog post.

At my company, we utilize Atlassian products such as Jira, Confluence, and BitBucket. For development purposes, the most important product from Atlassian is BitBucket. This is our version control system and it leverages git as it’s the underlying technology. I can not stress enough you need to manage all your work with some type of version control system. Using version control has saved me more times than I can count.

macOS Setup

I am writing this using macOS Big Sure 11.2.3. macOS includes PHP and Apache as part of macOS, but we are not going to utilize their versions. The primary reason for this is that using the stock packages that come with macOS is that Apple makes changes to the configuration of these packages while performing OS updates.

To get started we are going to need to install Xcode. Xcode will provide us with command-line tools such as git and it will include all of the developer tools required by HomeBrew. Follow the link which will open the App Store for you to download and install Xcode. Be forewarned, Xcode is a pretty big app and may take a bit of time to download and install.

Please note, I reference vi in my instructions below, but you can substitute vi with any text editor of your choosing. One thing to be aware of, some of the directories where files are installed are not visible to the Finder out of the box.

Apache, MySQL, PHP, and Elasticsearch

As mentioned previously, we want to install our own version of Apache and PHP and we also want to conform to Supported Platforms.

We will use Homebrew to install our software packages. Let's get started by installing Homebrew.

Open a macOS Terminal window

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

to ensure that brew is ready

brew doctor

you can find packages to install by using the command

brew search

for example

brew search php

==> Formulae
brew-php-switcher            php-code-sniffer             php@7.2                      phplint                      phpmyadmin                   phpunit
php                          php-cs-fixer                 php@7.3                      phpmd                        phpstan

==> Casks
homebrew/cask/eclipse-php                                                               homebrew/cask/netbeans-php

Apache

brew install apache2

Once Apache has been installed, the configuration files are located at /usr/local/etc/httpd/. In order to ensure that SugarCRM is running correctly, we need to make some changes.

vi /usr/local/etc/httpd/httpd.conf

Uncomment
LoadModule rewrite_module libexec/mod_rewrite.so

I prefer to store my website files in the Sites directory of my user
/Users/bickart/Sites. You can make these adjustments to meet your needs.

I have changed the DocumentRoot from
DocumentRoot "/usr/local/var/www"
<Directory "/usr/local/var/www">

to be

DocumentRoot "/Users/bickart/Sites"
<Directory "/Users/bickart/Sites">

within the <Directory tag, I have also changed 
AllowOverride none to be AllowOverride All

AllowOverride All will allow the Apache to access the .htaccess file
that will be used by Sugar.

You can restart Apache with the command
apachectl restart 

MySQL

brew install mysql@5.7

now that MySQL has been installed we want to ensure we give the MySQL a password

mysql_secure_installation

be sure to make note of your root password

Sugar uses utf8mb4 as the default charset; so we can adjust the MySQL configuration to set this as the default

vi /usr/local/etc/my.cnf 

in the [mysqld] section we are going to add
character-set-server=utf8mb4
collation-server=utf8mb4_general_ci

I also like to change the prompt in MySQL so that I know which DB that I’m using; you can do this by

vi ~/.my.cnf 

Then add
[mysql]
prompt="mysql [\\d]> "

which will give you a prompt like
mysql [db_slack]> 

PHP

Sugar 11 supports both PHP 7.3 and PHP 7.3. Sugar 12 supports PHP 7.4 and PHP 8.0. In order to work with both Sugar 11 and Sugar 12 in our development environment, we will install PHP 7.4

brew install php@7.4

As a Sugar developer, it is a great idea to also ensure that we have xdebug installed.

pecl install xdebug

We need to make some adjustments to our PHP configuration to meet the guidelines in Sugar Enterprise 11.0 Installation and Upgrade Guide. You can find all of the supported PHP timezones at https://www.php.net/manual/en/timezones.php.

vi /usr/local/etc/php/7.4/conf.d/ext-sugarcrm.ini

date.timezone=America/Los_Angeles #be sure to set to your timezone
max_execution_time=120
max_input_time=120
memory_limit=512M
post_max_size=100M
session.use_cookies=1
session.cookie_httponly=1
upload_max_filesize=100M

Now that we have PHP and Apache, we need to let Apache know how to use PHP. We are going to add a configuration for PHP

vi /usr/local/etc/httpd/extra/httpd-php.conf

LoadModule php7_module /usr/local/opt/php@7.4/lib/httpd/modules/libphp7.so

<FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>

<IfModule dir_module>
   DirectoryIndex index.php index.html
</IfModule>

We also need to make an adjustment to the httpd.conf file so that Apache can find out changes.

vi /usr/local/etc/httpd/httpd.conf

There is a section in the file that has a set of extra file. We need to add our 
extra file to be included in the configuration

#PHP
Include /usr/local/etc/httpd/extra/httpd-php.conf

apachectl restart

Elasticsearch

Elasticsearch is also a required component of running and installing Sugar. As indicated in Supported Platforms, there are a number of different versions of Elasticearch that Sugar supports. To future proof our environment for as long as possible, we will install ElasticSearch 7.10.2 which is the default version available via brew at the time of this writing.

brew cask install homebrew/cask-versions/adoptopenjdk8
brew install elasticsearch

Summary

We have set up all of the tools needed, Xcode, HomeBrew, Apache, MySQL, PHP, Elasticsearch for Sugar development on macOS. We discussed some of the applications that I used for my daily development including PhpStorm, ngrok and git.

A note about xdebug, I had you install it but I didn’t explain how we are going to be using it. We will walk through using PhpStorm, Sugar command-line debugging, using Postman as well as using your browser in another post.

Until next time,

Jeff
https://www.linkedin.com/in/bickart/