Drupal 8 Blogdown: Start Me Up!

Start Me Up Picture

In my last post in this series, I merely mentioned three things that you should know about Drupal 8 before diving into the code. They were: Drupal 8's sheer size, auto-loading classes, and the need for a proper Integrated Development Environment (IDE) for Drupal 8 coding. Now that you are familiar with those topics, and hopefully you've also looked up some Symfony components, I think it's time to install the beast!

My Rules

I am only going to install Drupal 8 core and add any other functionality I need through custom modules I'll make myself. The reason I'm doing this is mainly to learn more of Drupal 8's API but also to see how little of contrib space I need to build a personal site. My theory is that I won't really have to do much to be happy with D8 out of the box, and if that's true, I'll be pretty happy about it. 

Installation

Installation of Drupal 8 doesn't differ much from Drupal 7. You still have to create a /files folder, copy settings.php, and create a database before you can begin. However, you now have a services.yml file to create along with settings.php. Both of these files contain settings, and I'm not really sure of the distinction of why some variables need to go into services.yml while others remain in settings.php. I would think all of the general configuration that doesn't require PHP logic would eventually be placed in services.yml, but for the time being, I've only changed Twig settings in that file. 

Also of note, and exciting for me, is the fact that a settings.local.php file has been included by default. All you have to do is comment out some lines in settings.php.

/** 
 * Load local development override configuration, if available. 
 * 
 * Use settings.local.php to override variables on secondary (staging, 
 * development, etc) installations of this site. Typically used to disable 
 * caching, JavaScript/CSS compression, re-routing of outgoing emails, and 
 * other things that should not happen on development and testing sites.  
 * 
 * Keep this code block at the end of this file to take full effect. */

if (file_exists(__DIR__ . '/settings.local.php')) {
  include __DIR__ . '/settings.local.php';
}

and copy that file into your /sites/default folder and you are good to go. I have used this file for awhile on Drupal 7 sites so that I don't have to switch database info when making changes to settings.php. Whatever you do though, don't check in the settings.local.php file to your Git repository! This file is meant to allow any developer on your team to have their own local settings to their liking, but it will likely screw up your development environment if someone erroneously check it in. Luckily, Drupal 8 has a sample .gitignore file that should take care of this by uncommenting this line.

# Ignore configuration files that may contain sensitive information.
*/settings*.php

Hungry?...Why Wait?...Cause This Will Take Awhile

So, once you are done fooling around with those initial files, or are clever enough to use drush or some script to do it for you, you'll start the familiar installation process...and you'll wait...and you'll wait. All those files I mentioned previously take some time to setup and install, so don't worry if the install process is taking a little while. You might even even need to up your memory in PHP or timeout settings, but I've already done that locally so I had no issues with installing Drupal 8 so far. 

After your site is set up, you will notice a few cool/scary things in your file structure. The /sites/default/files folder is now a repository for compiled assets, and when I first looked at it I was pretty scared. CSS, JS, and PHP files are compiled and stored in these folders for quicker retrieval. I have no idea of the exact scheme for creating these files, and that is something I still have to learn; however, there is no need to be scared of these files. 

Just know that by deleting these files/folders you are sort of clearing the cache. A new file to Drupal 8 is rebuild.php, and that file will delete these caches among other things I don't quite understand yet. You can go to "www.example-site.com/rebuild.php" to run that file, if you have access, or sometimes you can just delete these files, and your caching issue may be fixed. I've dinked around and got my site responsive again sometimes by trying one or both methods. 

I Want to Be Close to the Metal? Why Not Chase Head?

I highly recommend picking a beta version of Drupal 8, beta 6 for me, to begin poking around instead of chasing head. I started out my foray into Drupal 8 trying to chase head and it was too confusing to me to fix site issues without knowing a lot about the core of the system. If you are an über developer, then go ahead, but this post is geared towards noobs like me...and noobs should stay away from that. 

As I write this, there is still no upgrade path between betas that I know of, so do yourself a favor and start building on a beta. You will see APIs and methods change, but I reckon it will be a lot easier for you to upgrade to the current release after you've built a module or theme or two.

Debugging Mode

Now that you have your site installed and up and running, the first thing you'll want to do is disable the Overlay module...just kidding, thank God they took that out! You now have a fancy new "Back to Site" button that replaces the functionality of the Overlay module. Pretty simple. 

What you will want to do is turn on some helpful debugging tips. I feel like the object-oriented structure of most of D8 and a good IDE will get you pretty far with back-end debugging. Setup xdebug with PHPStorm and you'll have your classic breakpoint debugging. Cmd/Ctrl + click on a method and see the definition. Look up interfaces. Do more advanced stuff I don't know about.

Even with everyone saying how complicated and complex D8 is compared to D7, I feel like the structure of code makes it far easier to know what's going on internally. Sure, you will have to spend a little time getting used to OOP stuff, but it's about time Drupal developers got with that program. Once you are a little familiar, navigating classes and knowing which methods you have to include to extend and create some new functionality is a breeze. 

You Had Me at Theme Hook Suggestion!!!

By far, the best new debugging feature I've seen in D8 comes with Twig. I was a total newbie to Twig so I definitely needed help stepping through templates and figuring out the new syntax. In D7, it was always hard to figure out exactly where one template ended and another began. I used to randomly look at templates, set guess breakpoints, and narrow it down. 

Now with Twig, Drupal will tell you exactly where the output is generated AND give you file name suggestions to override those templates! Whoa, I think I want to...like marry you!?! I turned on this debugging feature soon after installing D8 and won't turn it off until I'm completely done theming. Super helpful.

Twig Debugging Output


It was a little tricky for me to get this working in an efficient way so here's how I went about it on the beta 6 release. First, go to "/sites/default/files/services.yml" and set the "twig.config.debug" variable to "true".

# Not recommended in production environments
# @default false
debug: true

Be sure to read the comments section there. It specifically notes about not using this when running automated tests among other things. Once you set that variable, the twig configuration should be good, but you'll probably have trouble seeing changes unless you clear the cache. Since you are rebuilding files and that takes time, leaving it like this is not a good solution. 

The second step is to setup "settings.local.php" like I mentioned earlier. That file will have a line that disables the render cache, which is blocking you from seeing immediate changes to your templates. 

/**
* Disable the render cache.
*
* This setting disables the render cache by using the Null cache back-end
* defined by the development.services.yml file above.
*
* Do not use this setting until after the site is installed.
*/
$settings['cache']['bins']['render'] = 'cache.backend.null';

Definitely don't add "settings.local.php" before you install the site, as the note states. I had some confusion by adding that file before installing a D8 site once.

What Next?

After those changes, you should be able to start overriding template files like a boss in no time! I personally started with theming myself, and I think it's a good way for a noob to start poking around D8, noticing what's different, noticing what's changed, and most importantly getting the instant gratification that comes with making a change in code and seeing a result on the screen. 

In my next post, I'll talk more about theming and how D8 makes sub-theming super easy right out of the box.