Tutorial: Adding PHP support to Panini-based Foundation Sites

[jameswilson]

I had a simple static Panini-based Foundation site that needed a one-off dynamic page (contact form) written in PHP. So this is the approach I took for future self and anyone else interested, that might need a small mix of server-side processing.

I'm aware of effort by @joeworkman on Proton which leverages Twig instead of Panini, and can generate static HTML or PHP. But at this phase in the project lifecycle, I decided against trying to convert the Panini-based site to Proton (currently in beta), and instead just add PHP support to the existing code. Definitely consider Proton if you're starting a new project.

1. Create a foundation site.

Install foundation-sites configured with the panini template, not the basic template.

nvm install 14  # because foundation doesn't work with node 16 yet.
nvm use 14
npm install --global foundation-cli
foundation new --framework sites --template panini --directory my-project
cd my-project
nvm use 14  # because it switches back to whatever your default is when you cd (in my case node 16).
node -v > .nvmrc  # ensure node 14 is used when you cd into the project in the future.
yarn install -std=c++14  # on recent MacOS GCC has problems compiling node-sass, ymmv.
yarn start  # or npm start

2. Add PHP support.

1. Add the gulp-connect-php dependency.

   yarn add gulp-connect-php

2. Replace the default (node) server with a php server.

   Change gulpfile.babel.js to use a PHP server with BrowserSync configured as a proxy.

   + import php           from 'gulp-connect-php';

   -  browser.init({
   -    server: PATHS.dist, port: PORT
   -  }, done);
   +  php.server({ base: PATHS.dist, port: PORT }, function () {
   +    browser.init({ proxy: `localhost:${PORT}` }, done);
   +  });

3. Change gulpfile.babel.js to support handlebar processing inside PHP files.

   - return gulp.src('src/pages/**/*.{html,hbs,handlebars}')
   + return gulp.src('src/pages/**/*.{html,hbs,handlebars,php}')

   - gulp.watch('src/pages/**/*.html').on('all', gulp.series(pages, browser.reload));
   + gulp.watch('src/pages/**/*.{html,php}').on('all', gulp.series(pages, browser.reload));

4. Optionally, add an .htaccess file.

   Add - "src/.htaccess" to config.yml under PATHS.files (similar to PATHS.assets), then update gulpfile.babel.js to copy these files to dist folder and monitor them for changes.

   With .htaccess you can do fancy things like adding rewrite rules and handlers to remove file extensions, but note that the built-in web server that comes bundled with PHP and exposed to gulp in previous point above does not use Apache and therefore ignores .htaccess.

   Alternatively, stand up a local Apache server to serve from the dist folder to get a more realistic environment. This is beyond the scope of this tutorial.

   You can use the same approach to pass-through any other PHP helper files or includes straight to the dist folder without Panini processing. Make sure to place them outside the src/pages/ folder, potentially in the src/ or src/includes/ folder.

   config.yml

     assets:
       - "src/assets/**/*"
       - "!src/assets/{img,js,scss}/**/*"
   +  files:
   +    - "src/.htaccess"
   +    - "src/*.php"
   +    - "src/includes/*.php"

   gulpfile.babel.js

   -  gulp.series(clean, gulp.parallel(pages, javascript, images, copy), sassBuild, styleGuide)
   +  gulp.series(clean, gulp.parallel(pages, javascript, images, copy, files), sassBuild, styleGuide)

   +function files() {
   +  return gulp.src(PATHS.files).pipe(gulp.dest(PATHS.dist));
   +}
   +

     gulp.watch(PATHS.assets, copy);
   +  gulp.watch(PATHS.files, files);

3. Create a PHP page.

Note: This is a contrived example to demonstrate how Panini and PHP should play together. The assumption here — for simplicity — is that you will not use PHP inside your handlebar/html layouts and partials, but instead limit PHP to be page-specific. It may be technically possible to put PHP inside layouts and partials. This is not recommended. If you do, then ensure the generated files in the dist folder contain a .php file extension. The better alternative for more powerful templates and partials is to look at Proton, which uses PHP/Twig.

1. Add a PHP file to src/pages folder.

   The PHP file may contain any Panini frontmatter and requires both the opening <?php and closing ?> tags.

   src/pages/demo.php:

   ---
   meta-title: Using PHP with Zurb Foundation
   layout: demo
   ---
   
   <?php
   
   print phpinfo(); 
   
   ?>

2. Create a demo template.

   cp src/layouts/default.html src/layouts/demo.html

   src/layouts/demo.html:

   - <title>Foundation for Sites</title>
   + <title>{{meta-title}}</title>

4. Test PHP page in browser.

1. Build and serve your PHP app locally.

   yarn start

   The php server should be running at http://localhost:8000. BrowserSync will load the homepage in your browser via a proxy configuration at a dynamically assigned port (usually http://localhost:3000).

   Alternatively, you could run the built-in web server provided by PHP manually.

   php -S localhost:8000 -t dist

   Finally, for more robust support you may wish to instead stand up an Apache or Nginx server pointed at the dist folder.

2. Navigate to /demo.php

   This demonstrates the ability to wrap a PHP page inside a simple HTML layout, compiled into a final generated php asset via Panini.

[benthien]

I did something similar that is described in the paper
Handling_PHP_Files_in_Zurb_Template.pdf