This is a guide to help those with prior Homebrew mutliple PHP-based installations that are looking to upgrade to the new Hombrew/core
PHP setup from the prior Homebrew/php
keg which is now deprecated.
With the deprecation of Homebrew/php
tap, many of the prior formulaes we used in this guide are no longer available. The cleanest way to migrate from the old brew formulae to the new pecl package approach is to remove everything PHP-related and reinstall with the new instructions.
The first step in this process is to update all the latest packages then upgrade them. This will actually 'migrate' the core PHP packages (which are the only ones supported), but there's a bunch of symlinks utilized that could cause problems down the road, so after upgrading, we'll remove all PHP packages, to provide a fresh start:
brew update
brew upgrade
brew cleanup
You can then double check the current installed PHP packages with:
brew list | grep php
Now we just need to remove everything:
brew uninstall --force php56 php56-apcu php56-opcache php56-xdebug php56-yaml
brew uninstall --force php70 php70-apcu php70-opcache php70-xdebug php70-yaml
brew uninstall --force php71 php71-apcu php71-opcache php71-xdebug php71-yaml
brew uninstall --force php72 php72-apcu php72-opcache php72-xdebug php72-yaml
brew uninstall --force php80 php80-apcu php80-opcache php80-xdebug php80-yaml
brew uninstall --force php81 php81-apcu php81-opcache php81-xdebug php81-yaml
brew uninstall --force php82 php82-apcu php82-opcache php82-xdebug php82-yaml
brew cleanup
Don't worry if you don't have all these packages installed, this is just a cumulative list and it will skip over anything that's not installed.
Now we can check to see if anything PHP-related is left:
brew list | grep php
If you don't see anything you are all good. If something is still left, you can uninstall those individually using the same brew uninstall --force
syntax as above.
Now we want to clean out the old configuration options for PHP:
rm -Rf /usr/local/etc/php/*
Now you've cleaned up your prior installation, you can jump to the PHP Installation section of Part 1 of the guide.
]]>In Part 1 of this 3-part series, we covered configuring Apache on macOS Big Sur 11.0 to work better with your local user account, as well as the installation process for installing multiple versions of PHP. In Part 2, we covered installing MySQL, Virtual Hosts, APC caching, YAML, and Xdebug.
In this Part 3, we will cover getting your site setup with LetsEncrypt SSL support for this setup.
10/20/2023 Updated to reflect macOS 14.0 Sonoma
12/25/2022 Updated to reflect the release of macOS 13.0 Ventura
11/27/2021 Added self-signed section back + vhost configuration
11/13/2021 Updated to reflect the release of macOS 12.0 Monterey + switch from self-signed to LetsEncrypt Certificates
This guide is intended for experienced web developers. If you are a beginner developer, you will be better served using MAMP or MAMP Pro.
In order to get SSL setup and running properly four our Homebrew-powered Apache setup, we need to first create an SSL Certificate. This used to be a pain and cost money for a valid SSL certificate, but thankfully we now have Let's Encrypt, a non-profit Certificate Authority that provides certificates to 225 million websites!
This does require that you have registered a domain name with a company such as Hover, GoDaddy, Network Solutions, etc. You should configure this so that a valid host is available to point to your local webserver. You will probably also need to setup port forwarding so your external IP address is routed internally to your webserver. Usually this consists of setting up a port forward for HTTP
, HTTPS
with ports 80
and 443
to the internal IP address of your computer.
This is a process that depends on several factors:
I'll leave this process up to you as it might require some Googling to get the this process setup depending all the factors listed above. A quick way to test if you have things setup is to try reaching host via your phone or some other device that is not on your internal network.
Let's assume you have registered the domain grav.rocks
(p.s. I already own this one, you need to use your own!), and you have configured the host dev.grav.rocks
to be port-forwarded to your local development machine. You have tested this and you can confirm that when you browse to http://dev.grav.rocks
on your phone, you are indeed seeing the webserver of your internal network. You have successfully configured remote access, but now you want to get SSL working.
Throughout this guide I use dev.grav.rocks
as an example host. You will need to replace this with your own hostname
Now you have a valid host that is accessible from the internet, we need to generate a valid LetsEncrypt SSL certificate. First we should install the certbot
tool that will facilitate this process:
brew services stop httpd
brew update
brew upgrade
brew install certbot
To be able to use certbot
in a non-root setup (like we have with Brew), we need to create a cli.ini
file so that the certbot
command will use local paths rather than root
access-only system paths:
mkdir -pv ~/.config/letsencrypt
code ~/.config/letsencrypt/cli.ini
This assumes you have Visual Studio Code installed and have enabled the CLI code
command. See the first part of this series to find out more about this.
In this new file paste the following:
work-dir = /opt/homebrew/etc/certbot
logs-dir = /opt/homebrew/etc/certbot/logs
config-dir = /opt/homebrew/etc/certbot/certs
Save the file.
Now we can run certbot
without requiring sudo
which would limit our ability to run Apache as a non-root user.
certbot certonly --standalone
This kicks off a process that requires your response in a few places. Enter email address
, agree to Terms of Services, Choose Y
or N
to join mailing list. Lastly when prompted, enter the name of the host you want to use, e.g. dev.grav.rocks
.
Certbot will then try to authenticate by challenging the domain names provided:
Obtaining a new certificate
Performing the following challenges:
http-01 challenge for dev.grav.rocks
Waiting for verification...
Cleaning up challenges
Non-standard path(s), might not work with crontab installed by your operating system package manager
If successful, certbot will generate a fullchain.pem
and a privkey.pem
file that we can use to configure our SSL certificate in the Apache configuration. The output should look something like this:
IMPORTANT NOTES:
- Congratulations! Your certificate and chain have been saved at:
/opt/homebrew/etc/certbot/certs/live/dev.grav.rocks/fullchain.pem
Your key file has been saved at:
/opt/homebrew/etc/certbot/certs/live/dev.grav.rocks/privkey.pem
Your cert will expire on 2021-02-12. To obtain a new or tweaked
version of this certificate in the future, simply run certbot
again. To non-interactively renew *all* of your certificates, run
"certbot renew"
- Your account credentials have been saved in your Certbot
configuration directory at /opt/homebrew/etc/certbot/certs. You should
make a secure backup of this folder now. This configuration
directory will also contain certificates and private keys obtained
by Certbot so making regular backups of this folder is ideal.
- If you like Certbot, please consider supporting our work by:
The important parts to jot down are the full paths to the .pem
files which we'll use in the following section:
Certificate: /opt/homebrew/etc/certbot/certs/live/dev.grav.rocks/fullchain.pem
Key File: /opt/homebrew/etc/certbot/certs/live/dev.grav.rocks/privkey.pem
The first step is to make some modifications to your httpd.conf
:
code /opt/homebrew/etc/httpd/httpd.conf
In this file you should uncomment both the socache_shmcb_module
, ssl_module
, and also the include for the httpd-ssl.conf
by removing the leading #
symbol on those lines:
LoadModule socache_shmcb_module lib/httpd/modules/mod_socache_shmcb.so
...
LoadModule ssl_module lib/httpd/modules/mod_ssl.so
...
Include /opt/homebrew/etc/httpd/extra/httpd-ssl.conf
Next we need to change...
]]>In Part 1 of this 3-part series, we covered configuring Apache on macOS to work better with your local user account, as well as the installation process for installing multiple versions of PHP.
In this Part 2, we will cover installing MySQL, Virtual Hosts, APC caching, YAML, and Xdebug. After finishing this tutorial, be sure to check out how to enable SSL in Part 3 of the series.
10/20/2023 Updated to reflect macOS 14.0 Sonoma
12/25/2022 Updated to reflect macOS 13.0 Ventura
10/29/2021 Updated to reflect macOS 12.0 Monterey and removed PHP 5.6
11/13/2020 Updated to reflect the release of macOS 11.0 Big Sur
12/02/2019 Updated to reflect the latest release of PHP 7.4 and the removal of PHP 7.1 from Official tap
12/02/2019 Updated to reflect the latest release of PHP 7.4 and the removal of PHP 7.1 from Official tap
10/08/2019 Updated to reflect the release of macOS 10.5 Catalina
01/10/2019 Updated to add back PHP 5.6 and PHP 7.0 from and external deprecated keg
12/12/2018 Updated to reflect the latest release of PHP 7.3 and the removal of PHP 7.0 from Brew.
This guide is intended for experienced web developers. If you are a beginner developer, you will be better served using MAMP or MAMP Pro.
Although not required for development of Grav, there are times you definitely need an installation of MySQL. In the original guide, we used the Oracle MySQL installation package. However, we now have switched to MariaDB which is a drop-in replacement for MySQL and is easily installed and updated with Brew. Detailed information on the HomeBrew installation process can be found on the mariadb.org site but the essentials are as follows:
Install MariaDB with Brew:
brew update
brew install mariadb
After a successful installation, you can start the server ane ensure it autostarts in the future with:
brew services start mariadb
You should get some positive feedback on that action:
==> Successfully started `mariadb` (label: homebrew.mxcl.mariadb)
You must change MySQL server password and secure your installation. The simplest way to do this is to use the provided script:
sudo /opt/homebrew/bin/mysql_secure_installation
Just answer the questions and fill them in as is appropriate for your environment. You can just press return when prompted for the current root password.
Download TablePlus and install it. (it's awesome and there's a free version!). You should be create a new MySQL connection, give it a Name, a color, and check Use socket
option after you enter a User of root
and your newly created password.
If you need to stop the server, you can use the simple command:
brew services stop mariadb
A very handy development option is to have multiple virtual hosts set up for you various projects. This means that you can set up names such as grav.mydomain.com
which point to your Grav setup, or project-x.mydomain.com
for a project-specific URL.
Apache generally performs name-based matching, so you don't need to configure multiple IP addresses. Detailed information can be found on the apache.org site.
Apache already comes preconfigured to support this behavior but it is not enabled. First you will need to uncomment the following lines in your /opt/homebrew/etc/httpd/httpd.conf
file:
LoadModule vhost_alias_module lib/httpd/modules/mod_vhost_alias.so
and:
# Virtual hosts
Include /opt/homebrew/etc/httpd/extra/httpd-vhosts.conf
Then you can edit this referenced file and configure it to your needs:
code /opt/homebrew/etc/httpd/extra/httpd-vhosts.conf
This file has some instructions already but the important thing to remember is that these rules are matched in order. When you set up virtual hosts, you will lose your older document root, so you will need to add back support for that first as a virtual host.
<VirtualHost *:80>
DocumentRoot "/Users/your_user/Sites"
ServerName localhost
</VirtualHost>
<VirtualHost *:80>
DocumentRoot "/Users/your_user/Sites/grav-admin"
ServerName grav-admin.test
</VirtualHost>
Don't forget to change your_user
for your actual username on your Mac. For example: DocumentRoot "/Users/bernard/Sites"
As you set up your .test
virtual hosts, you may receive a warning such as Warning: DocumentRoot [/Users/your_user/Sites/grav-admin] does not exist
when restarting Apache. This just lets you know that the source directory listed for your virtual hosts is not present on the drive. It's an issue that can be resolved by editing this file with the corrected DocumentRoot
.
We used to recommend using .dev
domain name, but since Chrome 63 forces all .dev
domains to use SSL, this guide has been updated to use .test
In the example virtualhost we setup above, we defined a ServerName
of grav-admin.test
. This by default will not resolve to your local machine, but it's often very useful to be able to setup various virtual hosts for development purposes. You can do this by manually adding entries to /etc/hosts
ever time, or you can install and configure Dnsmasq to automatically handle wildcard *.test
names and forward all of them to localhost (127.0.0.1
).
First we install it with brew:
brew install dnsmasq
Then we setup *.test
hosts:
echo 'address=/.test/127.0.0.1' > /opt/homebrew/etc/dnsmasq.conf
Start it and ensure it auto-starts on reboot in the future:
sudo brew services start dnsmasq
And lastly, add it to the resolvers:
sudo mkdir -v /etc/resolver
sudo bash -c 'echo "nameserver 127.0.0.1" > /etc/resolver/test'
Now you can test it out by pinging some bogus .test
name:
ping bogus.test
PING bogus.test (127.0.0.1): 56 data bytes
64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.044 ms
64 bytes from 127.0.0.1: icmp_seq=1 ttl=64 time=0.118 ms
64 bytes from 127.0.0.1: icmp_seq=2 ttl=64 time=0.045 ms
Voila! we have successfully setup wildcard forwarding of all *.test
DNS names to localhost.
One of the most important aspects of any kind of development is the ability to debug and fix your code. PHP comes with limited support to dump variables or log to a file, but for more complex situations you need something more powerful.
Xdebug provides is a debugging and profiling extension for PHP that provides an HTML-friendly output for the var_dump()
method that improves the readability of the default version. It also provides other useful dumping methods as well...
Developing web applications on macOS is a real joy. There are plenty of options for setting up your development environments, including the ever-popular MAMP Pro that provides a nice UI on top of Apache, PHP and MySQL. However, there are times when MAMP Pro has slow downs, or out of date versions, or is simply behaving badly due to its restrictive system of configuration templates and non-standard builds.
It is times like these that people often look for an alternative approach, and luckily there is one, and it is relatively straight-forward to setup.
In this blog post, we will walk you through setting up and configuring Apache 2.4 and multiple PHP versions. In the second blog post in this two-post series, we will cover MySQL, Apache virtual hosts, APC caching, and Xdebug installation.
10/20/2023 Updated to reflect macOS 14.0 Sonoma
02/22/2023 Moved sphp.sh
to the GitHub repo version rather than Gist
12/25/2022 Updated to reflect macOS 13.0 Ventura
10/31/2021 Added dynamic support for Apple Silicon and Intel homebrew paths
10/29/2021 Updated to reflect macOS 12.0 Monterey and removed PHP 5.6
11/27/2020 Updated to add some information on PHP 8.0
11/13/2020 Updated to reflect the release of macOS 11.0 Big Sur
12/02/2019 Updated to reflect the latest release of PHP 7.4 and the removal of PHP 7.1 from Official tap
12/02/2019 Updated to reflect the latest release of PHP 7.4 and the removal of PHP 7.1 from Official tap
10/08/2019 Updated to reflect the release of macOS 10.5 Catalina
01/10/2019 Updated to add back PHP 5.6 and PHP 7.0 from and external deprecated keg
12/12/2018 Updated to reflect the latest release of PHP 7.3 and the removal of PHP 7.0 from Brew.
If you have followed this guide in the past with the Homebrew/php
tap, and are looking to upgrade to the new Homebrew/core
approach, then you should first clean-up your current installation by following our new Upgrading Homebrew.
This guide is intended for experienced web developers. If you are a beginner developer, you will be better served using MAMP or MAMP Pro.
If you don't already have XCode installed, it's best to first install the command line tools as these will be used by homebrew:
xcode-select --install
This process relies heavily on the macOS package manager called Homebrew. Using the brew
command you can easily add powerful functionality to your mac, but first we have to install it. This is a simple process, but you need to launch your Terminal (/Applications/Utilities/Terminal
) application and then enter:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Just follow the terminal prompts and enter your password where required. This may take a few minutes.
If this is a fresh install and you don't have your path setup properly, you can follow the installation "next steps" which are already customized for you, or you can manually add the following paths to your .bashrc
or .zshrc
:
(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
Now you can test your installation to ensure you have installed brew
correctly, simply type:
brew --version
Homebrew 4.1.16
You should probably also run the following command to ensure everything is configured correctly:
brew doctor
It will instruct you if you need to correct anything.
When installing fresh on Sonoma, I ran into a few libraries that were missing when completing all the steps below. To make things easier, please simply run this now:
brew install openssl
The latest macOS 13.0 Sonoma comes with Apache 2.4 pre-installed, however, it is no longer a simple task to use this version with Homebrew because Apple has removed some required scripts in this release. However, the solution is to install Apache 2.4 via Homebrew and then configure it to run on the standard ports (80/443).
If you already have the built-in Apache running, it will need to be shutdown first, and any auto-loading scripts removed. It really doesn't hurt to just run all these commands in order - even if it's a fresh installation:
sudo apachectl -k stop
sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist 2>/dev/null
Now we need to install the new version provided by Brew:
brew install httpd
Without options, httpd
won't need to be built from source, so it installs pretty quickly. Upon completion you should see a message like:
🍺 /opt/homebrew/Cellar/httpd/2.4.58: 1,663 files, 32MB
Now we just need to configure things so that our new Apache server is auto-started
brew services start httpd
You now have installed Homebrew's Apache, and configured it to auto-start with a privileged account. It should already be running, so you can try to reach your server in a browser by pointing it at http://localhost:8080
, you should see a simple header that says "It works!".
If you get a message that the browser can't connect to the server, first check to ensure the server is up.
ps -aef | grep httpd
You should see a few httpd processes if Apache is up and running.
Try to restart Apache with:
brew services restart httpd
You can watch the Apache error log in a new Terminal tab/window during a restart to see if anything is invalid or causing a problem:
tail -f /opt/homebrew/var/log/httpd/error_log
Apache is controlled via the brew services
command so some useful commands to use are:
brew services stop httpd
brew services start httpd
brew services restart httpd
In past guides, I've always provided instructions to edit files using the default TextEdit
application that comes pre-installed. However, this is not what I use myself as it's a terrible editor and when testing my guide for Sonoma, I kept running into problems with encoding, finding line numbers etc. The better solution is to simply install a better editor. So please install the amazingly versatile yet, 100% free, Visual Studio Code. It's available on Mac, Windows, and Linux, but right now we only care...
This new version is available in the testing branch of GPM, so all you need to do is to change your System configuration to use testing
releases:
gpm:
releases: testing
You can also do this via the Admin
plugin in Configuration
⟶ System
⟶ GPM Section
⟶ GPM Releases
.
After this you should see several email related updates tagged with testing
. The intial release is for Email v4.0.0-rc.1
and various associated transport plugins each tagged v1.0.0-rc.1
. Please install and test and provide feedback in the Email plugin GitHub Issues
We've also moved away (while still full supporting) the default behavior of prior Email plugin releases, of having separate fields for an email address
and name
. Rather, we primarily use the RF822 format in a single text field: bob@email.com <Bob Smith>
. Email 4.0 actually supports many email formats automatically such as:
Yaml Syntax:
to: 'bob@email.com'
to: 'bob@email.com <Bob Smith>'
to: [bob@email.com, Bob Smith]
to: {email: 'bob@email.com', name: 'Bob Smith'}
to: {mail: 'bob@email.com', name: 'Bob Smith'} #(for backwards compatibility)
And of course arrays of these various formats for multiple email addresses.
The Symfony/Mailer package also provides a number of 3rd party transports, and we have created associated Grav Plugins that integrate automatically with Email 4.0. These allow you to use API
and sometimes HTTPS
based communication which are much faster, provide better tracking and debugging, and are overall far superior to traditional SMTP
.
The default supported list include:
I also wanted to test the ability to support other providers and as we often use Mailersend ourselves, I created my own symfony/mailersend-mailer
package and bundled that up in a plugin also. This served as a proof of concept and proved that any 3rd party email provider could be integrated with Email 4.0.
During development I realized the built in spool-based queue functionality of SwiftMailer, that was always optional, never really worked that well, and required scheduling to setup, was not going to be easy to support. Even though Mailer has more much powerful queue functionality it requires external message queue systems, and that was something I didn't want to deal with in this first version at least. I feel very few users actually use the Queue and with modern Email services and API functionality, it's really not as useful as it was when we only had SMTP and strict sending limits. So for now Email 4.0 will not support queues, but everything else should remain the same.
If there is an outcry from the community about this functionality being removed, I'll circle back and take a look at what it would require to add Symfony/Mailer's queue support.
For more information regarding configuration, integration with Grav, and setup help for a variety of Email providers, please review the Email plugin's README.md
]]>TL;DR I am happy to announce that we have launched an official GitHub Action for the automation in building Skeleton packages.
With the release of Grav 1.7, we have taken the opportunity to move from Travis to GitHub Actions for the creation of our release packages. Our original workflow included the packaging of Grav, the tests runner on each commit/PR and the regeneration of all the official Grav Skeletons - all within the same workflow.
This process was bearable at the beginning but over time Travis, which has served us extremely well over the years, has started imposing stricter waiting queues for free and ORG plans and on top of that, our Skeletons count has been growing.
To put it in perspective, performing a release for Grav was taking a good 8-10 minutes, after a 2-3 hours wait in the queue. Now imagine the unfortunate situation of having re-release right away...
GitHub Actions, from GitHub, fully integrates with our repository and has simplified substantially the way workflows work and get maintained in general. It has clear documentation, is easy to understand, and is available for anyone to use. GitHub Actions has been used by many people for all kind of automations, from Pull Requests validity, to performing tests on commits, from automating issues responses, to notifications on chat services such as Slack/Discord.
The best part of all is that GitHub Actions allows developers to create their own Actions and then share them in the Marketplace so that anyone can use them!
It was time for us to leave Travis behind and move over our workflow to GitHub Action. The first thing we did was to ensure we only focused the workflow with regard to Grav releases. This meant generating the 3 official packages available for download (Grav, Grav + Admin, Grav Update) and completely leave Skeletons out of the picture.
This didn't take long, and while perhaps not apparent to everyone, we have been generating our new packages with this new workflow with the first Grav 1.7 release. We also quickly added a separated workflow for the tests, which have been running ever since.
We now had split one workflow into two, with each one focused on their own tasks, and let me tell you this has given us a massive improvement in release timing! Releasing Grav now takes about 1.5 minutes, running tests on a matrix of 3 PHP versions (7.3, 7.4, 8.0) takes about 35 seconds. Impressive.
Now the only thing left to address were the Skeletons.
With the flexibility GitHub Actions offers, and now the total separation of the Skeletons workflow from the rest of the Grav continuous integrations, we had the great opportunity of rethinking how we wanted the whole build process to work. The easy way would have been to just port over what we had originally and call it a day, but what if we could make this accessible to the rest of the community?
We decided to create an official Skeleton Builder Action, and it's incredibly simple for any Theme developer to now create and maintain their Grav Skeletons. This new system can also automatically create 2 packages, one that includes Admin and one that does not.
It is important that your Skeleton follows the proper Grav's guidance and that your .dependencies
file is correctly implemented. You can check out the Grav Blog Site Skeleton .dependencies
file if you need a starting point, it is quite self-explanatory.
A workflow in GitHub Actions is a collection of steps. Each steps runs one single action and one after another the workflow will reach its execution end. If everything goes right it will succeed, otherwise it will fail and provide a message of doing so.
You can access your workflows at any time in your GitHub repository from the main tabs bar, by clicking Actions.
The first thing needed is to create a new workflow. You can do so by clicking on the New workflow button in the Actions section on GitHub, and then click on Skip this and set up a workflow yourself ➝.
Change the autogenerated workflow name from main.yml
to build-skeleton.yml
, and then replace the content entirely with the following magic formula:
name: Build Skeleton
on:
release:
types: [ published ]
workflow_dispatch:
inputs:
tag:
description: 'Target tag for re-upload'
required: true
default: ''
version:
description: 'Which Grav release to use'
required: true
default: 'latest'
admin:
description: 'Create also a package with Admin'
required: true
default: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Extract Tag
run: echo "SKELETON_VERSION=${{ github.event.inputs.tag || github.ref }}" >> $GITHUB_ENV
- name: Generate Skeleton Packages
uses: getgrav/skeleton-builder@v1
with:
version: ${{ github.event.inputs.version || 'latest' }}
admin: ${{ github.event.inputs.admin || true }}
- name: Upload packages to release
uses: svenstaro/upload-release-action@v2
with:
repo_token: ${{ secrets.GITHUB_TOKEN }}
tag: ${{ env.SKELETON_VERSION }}
file: dist/*.zip
overwrite: true
file_glob: true
Click on the Start commit button and then Commit. You should now have your workflow created and if you go to the root of your repository, you should see a new folder created .github/workflows
that contains the file build-skeleton.yml
we created above.
The workflow in combination with the Skeleton Builder Action supports the creation of Skeleton packages in two ways:
Automatically: every time a new release of your skeleton is published on GitHub, the workflow will run, generate the packages and upload them on your just published release.
Manually: if you don't have anything to release, but you want to rebuild the packages to use the latest version of Grav or any of your Skeleton dependencies, you can use this way.
To use the automatic mode, you don't have to do anything other than follow the standard procedure of GitHub release. Once a new Release is created, the workflow will spin off.
The Manual mode, instead, can be...
]]>One of the cool new features of Grav 1.7 is the new bin/grav server
command that now comes with support for Symfony's PHP-FPM-powered local webserver. While Grav has support PHP's native web server, the Symfony server is faster and even supports SSL out of the box.
To take advantage of this, you first need to install the Symfony CLI executable for your system.
We will assume you already have PHP installed and have some basic level of familiarity with the terminal on your platform of choice.
Visit the Symfony Download page, and click the tab that's suitable for your platform.
curl -sS https://get.symfony.com/cli/installer | bash
Next, you need to install the binary in your ~/.symfony/bin/
folder. You can add this path to your system path or create a symlink to the binary directory already in your path. On my system, I already have ~/bin
in my path so that I can create a symlink there:
ln -s ~/.symfony/bin/symfony ~/bin/symfony
Feel free to symlink to /usr/local/bin/symfony
if you use Brew, as that will already be in your path.
You can use echo $PATH
to output the current list of directories in your path.
wget https://get.symfony.com/cli/installer -O - | bash
Follow the same steps as above to symlink; on my test Raspberry Pi machine, I used:
sudo ln -s ~/.symfony/bin/symfony /usr/local/bin/symfony
Download the setup.exe
file as linked to on the Symfony downloads page. This should set everything up for you.
While it's not required, it's always a good idea to use SSL for your web connections, even locally. Luckily Symfony makes this easy with a single command:
symfony server:ca:install
You will probably be prompted to enter your system password to add the CA (Certificate Authority) to your system's trust store. If all goes well you should be greeted with:
[OK] The local Certificate Authority is installed and trusted
Once completed, you will never need to perform steps 1 and 2 again, once is enough! All you need to do from this point on is just follow step 3.
Now you can navigate to the root of your Grav installation in your terminal and then run:
bin/grav server
The Grav server command is smart enough to use the first available port over 8000
. This means you can run this command on multiple Grav instances, and each site will be run on a different port. Neat huh?
As you can see the server is up and running on 127.0.0.1
or localhost
on port 8000
, and notice that it's already using HTTPS
so SSL
is working. Just point your browser to that URL provided: https://127.0.0.1:8000
, and you should see some requests display in your terminal:
That's it really, enjoy!
]]>bin/gpm self-upgrade
This results in an error like this:
In HttpClientTrait.php line 223:
Unsupported option "curl" passed to "Symfony\Component\HttpClient\CurlHttpClient", did you mean "auth_basic", "auth_bearer", "query", "headers", "body", "json", "user_data", "max_redirects", "http_ve
rsion", "base_uri", "buffer", "on_progress", "resolve", "proxy", "no_proxy", "timeout", "max_duration", "bindto", "verify_peer", "verify_host", "cafile", "capath", "local_cert", "local_pk", "passphra
se", "ciphers", "peer_fingerprint", "capture_peer_cert_chain", "extra", "auth_ntlm"?
We have fixed this but because the bug is located in the self-upgrade
command itself, you won't be able to upgrade via the CLI (admin works fine BTW), until the file itself is fixed. The fix is pretty simple however:
Please make sure you run this command for the ROOT of your Grav site, the same place you run the bin/gpm self-upgrade
command.
Use either wget
:
wget https://raw.githubusercontent.com/getgrav/grav/c8af0d8a385a4dce7d5c5ef54a50c23b5946167f/system/src/Grav/Console/Gpm/SelfupgradeCommand.php -O system/src/Grav/Console/Gpm/SelfupgradeCommand.php
or curl
:
curl https://raw.githubusercontent.com/getgrav/grav/c8af0d8a385a4dce7d5c5ef54a50c23b5946167f/system/src/Grav/Console/Gpm/SelfupgradeCommand.php -o system/src/Grav/Console/Gpm/SelfupgradeCommand.php
Or manually by downloading the https://raw.githubusercontent.com/getgrav/grav/c8af0d8a385a4dce7d5c5ef54a50c23b5946167f/system/src/Grav/Console/Gpm/SelfupgradeCommand.php
file and replacing your system/src/Grav/Console/Gpm/SelfupgradeCommand.php
file.
After this fix, your upgrade should go smoothly.
Sorry for the inconvenience!
-- Grav Team
]]>After 30 developmental releases (both Beta and RC), and nearly 2 full years in development, we're proud to unleash our most significant release ever! Grav 1.7 is a massive release for us, and while it may appear quite similar to 1.6 at first glance, under the covers, Grav has had some revolutionary changes.
Grav 1.7 now scales much better than it did before thanks to the extensive use of Flex Objects under the covers in the Admin. During development, we tested the Admin with 50,000 pages and still found it usable. Flex-Objects is now so integral in the Admin; it is now a required plugin. A new Flex Pages UI uses Miller Columns like the Mac Finder to make navigating larger and more complex page structures faster and easier. We've made this extensible, so plugins will soon be able to integrate directly into it, which was just not possible with the old pages UI.
We've also added all-new User Management tools to the Admin, allowing you to define Users and Groups, allowing the configuration of complex ACL rules. These are available in the Flex Pages interface via the new Security tab. They allow you to restrict specific users to specific functionality on a page (CRUD), or particular pages themselves.
Another great addition to the Admin, is the ability to customize and Whitebox the UI for your client. We've included several new Admin themes for you to play with, and you can modify them or even create your own.
Multi-language capabilities have also been improved with more robust language fallbacks. Check out the previous blog post where we outlined more features and functionality that make 1.7 so fabulous!
Always backup your site, or better yet, create a copy of your site and test upgrades there first.
As we announced last year, Grav 1.7 requires PHP 7.3.6 to run. This choice was made to allow us to install the latest and most secure versions of several libraries we rely on and ensure your running on a supported version of PHP. 7.3 is no longer receiving active support and is already in the "Security Fixes Only" phase. Grav 1.7 also supports the recently released PHP 8.0.
From our testing, if you upgrade to Grav 1.7 via GPM (either via CLI or Admin) then the upgrade should go smoothly from previous versions of Grav. If you are manually upgrading Grav via GitHub of FTP files, then you should check out the Grav 1.7 Upgrade Guide to ensure a smooth upgrade process as you may need to turn on a couple of compatibility options manually.
The primary potential issue is related to Twig Auto Escaping, which is enabled by default in Grav 1.7, but we handle via GPM updates to enable Twig compatibility mode if you are coming from Grav 1.6 or below.
The other main issue we have seen is that YAML is more strictly interpreted now due to security updates in Symfony libraries, so we also turn on YAML Compatibility during the upgrade process to limit the impact of this. If you see any errors, check the Tools
→ Reports
to see if you have any YAML errors in your pages or configuration. This can also be done via the CLI with: bin/grav yamllinter
. You should also run a quick XSS security check while you are at it with bin/grav security
.
If you are a developer, you should check out our Grav 1.7 Upgrade Guide that outlines some of the low-level changes in Grav 1.7 and anything that might impact you or your clients.
If you are struggling or are experiencing problems, the best and fastest place to get help is via our Discord Chat. The development team, as well as a horde of helpful community members, are there to help you isolate and resolve any issues you may have.
]]>Last month we released the first round of our long-awaited Grav Premium products. This set of premium plugins and themes provide new functionality for the open-source Grav platform that we have been developing over the past year. In this Grav Premium Focus series of blog posts, I plan on showcasing some of these premium products and how they can help you and your clients to take Grav to the next level.
NextGen Editor is a powerful rich text editor that provides a user-friendly and intuitive WYSIWYM (What You See Is What You Mean) experience for creating content within Grav. Traditionally Grav has provided an easy-to-use text-based editor that allows for content to be created using Markdown syntax. While this provides an accurate and quick way to create content, it's not as intuitive as using a true WYSIWYM editor would be. Most non-technical people are used to having a much more visually representative editing environment to write in because they are already used to using WYSIWYG (What You See Is What You Get) products such as Microsoft Word, or Apple Pages.
NextGen Editor attempts to bridge this gap by providing the WYSIWYM experience that clients expect. NextGen leverages the power of CKEditor5 to provide the base editor functionality, however, NextGen Editor adds it's own powerful additional features such as bi-directional Markdown support to ensure you can take advantage of Grav's built-in custom markdown-powered functionality. It also has the ability to integrate with Grav plugins such as the powerful Shortcode Core and Shortcode UI that come fully supported out of the box.
The difference between WYSIWYG and WYSIWYM is subtle but important. WYSIWYG is a term used in desktop publishing and is an exact 1:1 representation of the end product because what you see is "what you get", share, print, etc.
For the web, things are a bit different, you can easily adjust how things look with CSS styling, and they will also look different on other devices. The better approach is WYSIWYM, where the emphasis is on "what you mean". The visual representation of the editor where you have indicated that styling is bolder, or larger, or aligned just so, is the important thing, but not necessarily exactly a 1:1 representation of how it will be represented on the site.
While our NextGen Editor is packed with all the standard WYSIWYM features you would expect in a powerful editor such as a toolbar that lets you highlight text and add header sizes, bold, italic, underline, strikethrough, lists, and tables, etc. There's also great functionality in the underlying editor to providing formatted rich-text pasting, removing formatting from rich-text, as well as unlimited undo and redo. However, there's much more under the covers than initially meets the eye.
The plugin development focused on making it easy to add custom functionality to NextGen via Grav plugins, providing limitless opportunities. Let's cover a few great examples:
The Shortcode Core and Shortcode UI plugins have already been released with NextGen integration to make it easier than ever to take advantage of the shortcodes they offer. Previously, you would have to refer to the documentation and manually typed in the shortcodes. Now, with NextGen Editor, you can click on the toolbar to add a specific shortcode. Editing a shortcode is as simple as clicking the gear icon () and filling in the fields that display in the popup. The resulting shortcode is shown as a block in the editor so that it's clear and obvious, and distinct from your regular content.
With the latest version of NextGen Editor we have added a new intuitive way of handling custom HTML snippets. There are times where you will find yourself needing to mix some custom HTML with your editor content, this has always been possible with the default editor as you were essentially creating content in a text editor, but in NextGen Editor, you usually don't want the editor to try to 'convert' these HTML snippets into something rendered, causing issues when saving. You want these HTML snippets to remain intact and be editable when needed.
Examples of these might be to embed a voting poll into your content, or embed an external video, or even to include a complex block of HTML that is just too cumbersome to recreate with markdown's intentionally limited capabilities.
Grav has had a YouTube plugin for some time; however, with NextGen Editor, it really comes alive! With the NextGen support, the YouTube plugin allows you to quickly embed a YouTube video and see it directly in your content. No more guessing if you have the link and syntax-correct. You can visually see it embedded directly in NextGen Editor and easily tweak the options and settings.
There are several huge benefits of using NextGen over the standard editor. Let's cover some of the key ones:
By moving to a WYSIWYM editor approach, NextGen Editor now plays nicely with your browser for things such as built-in spellcheck, as well as browser plugins such as Grammarly and Language Tool. These make it much easier to ensure your content is spelled correctly, grammatically correct, and more readable to your end-users. This also is a sure-fire way to improve user engagement and improve your SEO. The importance of well-written content cannot be overstated.
NextGen Editor comes bundled with various automatic text transformations and also provides configuration to allow you to add your own. This allows you to quickly deliver more appealing content without any extra work on your end. Imagine your editor automatically converting your simple text characters into special characters for things like quotes, typography, fractions, and other mathematical symbols.
I hope by highlighting some of the powerful features...
]]>