Source Code for /public/04-includes-and-functions/index.php

<?php
// Include the functions.php file, which provides functions we use all over the place:
require('../inc/functions.php');

// Render our HTML header, including this lesson's title
add_header('Lesson 4: Includes and Functions');
?>

<div class="objectives">
  <h2>Objectives</h2>
  <ul>
    <li>Separate your site into smaller, reusable parts, and <code>include</code> them where they're needed</li>
    <li>Write your own functions to encapsulate repetitive tasks</li>
    <li>Share functions across multiple pages with <code>include</code> or <code>require</code></li>
  </ul>
</div>

<h2 id="navigation-menu-include">Sharing your navbar across the site</h2>
<p>
  As we saw with loops, PHP is very helpful when you want to reduce repetition in your code. This in turn reduces the
  risk of mistakes, and makes it easier to re-use the same code in multiple places.
</p>
<p>
  One powerful way to do this is with PHP's <code>include</code> directive. This lets you load the contents of a PHP
  (or HTML) file into another PHP file.
</p>
<p>
  With this, we can re-use the navigation menu we made in <a href="/03-lists-and-loops/#navigation-menu">Lesson 3</a>
  on every page of our site, like this:
</p>
<?php code_block_from_file( '04-includes-and-functions/navigation-menu-include.php', 'php', true, true, '03-lists-and-loops/navigation-menu.css' ); ?>
<p>
  This <em>shares your navigation menu</em> across every page of your site, including any logic embedded within it
  (e.g. to <a href="/03-lists-and-loops/#conditional">conditionally show or hide menu items</a>). Updating the menu
  in just one place updates it everywhere.
</p>
<p class="tip">
  A common technique is to put reusable part of your site, like your header and footer, into separate files for reuse.
  Why not take a look at the source code for <a href="/source-viewer.php?file=public/inc/header.php">the header</a> and
  <a href="/source-viewer.php?file=public/inc/footer.php">the footer</a> of <em>this</em> site!
</p>
<div class="tip">
  <p>
    PHP has several functions for including files, with slight differences between them. They are:
  </p>
  <ul>
    <li><code>include</code> - includes the file if it exists</li>
    <li><code>require</code> - includes the file; stops execution if it doesn't exist</li>
    <li><code>include_once</code> - includes the file if it hasn't been included yet and it exists</li>
    <li><code>require_once</code> - includes the file if it hasn't been included yet; stops execution if it doesn't exist</li>
  </ul>
  <p>
    Purists get into arguments about which is better, but it usually only matters if your included file defines its own
    <em>functions</em> (in which case including it twice can cause an error).
  </p>
</div>

<h2 id="functions">Reusing common patterns with functions</h2>
<p>
  So far, you've been using standard functions like <code>strrev</code> (to reverse a string) and <code>date</code> (to get the
  current date). You can write your own functions and they're a great to way to encapsulate reusable code.
</p>
<p>
  Let's define a function for adding a captioned image, where clicking on it links to the full-size image:
</p>
<?php code_block_from_file( '04-includes-and-functions/captioned-image-function.php', 'php', true, true, true ); ?>

<h2 id="shared-function-file">Sharing a function across multiple pages</h2>
<p>
  To make that function available throughout our site, we can move it to a different file and then <code>include</code>
  or <code>require</code> it from the files that need it.
</p>
<h3>The shared file with the function:</h3>
<?php code_block_from_file( '04-includes-and-functions/cap-img.php', 'php', false, true ); ?>
<h3>A page that depends on it:</h3>
<?php code_block_from_file( '04-includes-and-functions/cap-img-demo.php', 'php', true, true, '04-includes-and-functions/captioned-image-function.css' ); ?>

<p class="tip">
  The files you include can come from <em>anywhere on your server</em>, including from outside the directory (folder)
  where your publicly-accessible files are stored. On <em>this</em> site, for example, the "footer" can be
  viewed as if it were a standalone page by going direcly to
  <a href="https://php.danq.dev/inc/footer.php">https://php.danq.dev/inc/footer.php</a>! How could you
  mitigate this by moving the footer into a different directory?
  <small>(<a href="/demo-harness.php?file=public/appendix-samples/includes-from-outside-webroot.php">🏁 view solution</a>)</small>
</p>

<?php
// Render our HTML footer
add_footer();
?>