Todd Eidson's Programming Blog

Fancy Up Your Fonts with Ligatures

Sun, 19 Jan 2020 00:00:00 UTC

Fancy Up Your Fonts with Ligatures

"Woah, how'd you get your not equals to look like that?"

I've recently started a new job and am now taking part in regular code reviews. The majority of these reviews take place over a video chat in which screen sharing is used in conjunction with Intellij's "Git > Compare with branch" to display the diff. We then talk through the changes and raise any concerns with the changes.

On several occasions, usually mid-sentence, I get the question "Woah, how'd you get your not equals to look like that?" Or equals, or greater-than-or-equal-to, or lambda operator, or ... the list goes on.

"Oh, that? That's a ligature, you can turn that on easily in your Intellij settings."

I've had 'ligatures' in my "blog ideas" list for well over a year, so I've decided to go ahead and scratch that one off the list.

What are Ligatures?

According to fonts.com a ligature is "a special character that combines two (or sometimes three) characters into a single character."

Ligatures aren't available in most font sets. I first discovered them in Fira Code, when I was looking for a new monospace font to use for programming. It was one of those happy little accidents where I stumbled across something that I never knew I needed to solve a problem that I didn't even know I had. I had to try them out right away. And I fell in love with ligatures instantly. Ligatures make code look much cleaner, and scan much more quickly, in my opinion.

This is an image borrowed from the Fira Code repo displaying how all of the ligatures look.

Fira Code Alternatives

Enabling Ligatures in Intellij

Okay, you're convinced. Ligatures are great and you want to start using them immediately. So how do you do that?

To enable ligatures in Intellij (or any other Jetbrains IDE), the first thing to do is to open up settings (alt+ctrl+s on Linux/Windows or ⌘ + comma on Mac).

Then you can go to "Editor > Font" or start typing "ligatures" in the search input.

All that's left now is to select "Fira Code" or another font that includes ligatures and check the "Enable font ligatures" checkbox. (Fira Code is included with all of the newer Jetbrains IDEs, you may have to install any other fonts you want to try)

Other IDEs

In addition to the Jetbrains IDEs, you can also enable ligatures in most other popular IDEs, code editors, and some terminals.

Atom
Eclipse
Netbeans
Notepad++
Sublime Text
Visual Studio
Visual Studio Code
iTerm 2
Kitty

Also, I just learned while researching this post, you can import the CSS and use ligatures in most modern browsers!

So what are you waiting for? Fire up your favorite IDE and start playing with ligatures today!

Face Value

Sat, 28 Sep 2019 00:00:00 UTC

Face Value

I'd recently been on a job hunt (now fulfilled), and I was contacted through stackoverflow by a recruiter that had located my stackoverflow Developer's Story and was impressed. He'd asked me to complete a coding challenge which I passed with flying colors. I was then invited to participate in a technical interview with one of their team leaders and a developer - this is where the trouble began.

The first problem was that recruiter had informed me that this interview was to go over my code sample and take a deeper dig into my background; so I wasn't expecting a full-blown technical interview and therefore had failed to do any preparation.

The second problem is that I'd never taken part in a "real" technical interview and as such as I wasn't sure what to expect. I had, of course, read articles in the past about technical interviews, but it had been quite some time. It would have behooved me to reread some articles to have a better idea of what to expect.

So problems one and two are closely related and boil down to a lack of preparation and experience. It is my insight garnered from the third strike that I would like to share with you today: take all interview questions at face value.

The job posting for this position had a salary range that, to me, was "crazy" money. Imposing a sense of imposter syndrome from the get-go, so the very first question caught me off guard.

"How would you model a deck of playing cards? What members would you use and what methods would you need to make available?"

Simple, right? A deck of cards is simply an array of cards, each card having a suit and a value. However, I had the thought, "this question cannot be this simple, can it? There has to be a trick. What's the catch?"

So instead of giving the simple answer, I stuttered and stammered, trying to buy time to process the question from other angles. I had entered a state of analysis paralysis. I was overthinking the problem to the nth degree. Instead of giving the simple (and correct) answer, I tried to make my answer as complicated as my perceived (and unreal) impression of the question. I was seeing a hidden meaning behind the question that just was not there. I did not take the question at its face value.

This was only the first question, and I was crashing and burning, HARD. They let me flounder for about ten minutes before stopping me and moving on to the next question. No, that's not fair. They didn't let me flounder. They tried to steer me towards the right answer. They even went so far as to "rephrase" my answer back to me to make it sound like I had given the right answer. I was not having that, so I stuck to my guns; I "corrected" them - to make sure that they knew that I had given the wrong answer. They were great. Kudos to them for not calling me an idiot.

I did manage to recover, for the most part, and partially redeem myself for the rest of the interview. At least to the point that I am pretty sure that they don't think someone else wrote my sample project.

Several days later, I received the nicest rejection email that I have ever received. The recruiter encouraged me to try again in the future and wished me the best of luck on my future endeavors.

All in all, even though I was kicking myself in the butt for the next 48 hours, it was a positive experience. I got some valuable interview experience, for one. A couple of hours later, I fired up IntelliJ and modeled a deck of playing cards, properly - in an attempt to strengthen my Java knowledge in preparation for another interview I had coming up. I did land that position, which I felt was a much better fit for me, anyway. Also, most importantly, I learned, the hard way, to always take an interview question at face value.

Photo by kendall hoopes from Pexels

Catching Mail with MailCatcher

Sun, 31 Mar 2019 00:00:00 UTC

Catching Mail with MailCatcher

MailCatcher

MailCatcher is a powerful and easy to use Ruby gem that acts as an SMTP server that allows you to inspect emails that your application is sending out in your dev environment.

Installation

Installation is pretty simple, these are the commands that I used on my Fedora 29 install to get it up and running. If Ruby is already installed on your machine, or if you've already installed other Ruby gems, you may not need the first few lines.

sudo dnf install ruby
sudo dnf group install "C Development Tools and Libraries"
sudo dnf install ruby-devel zlib-devel

# Redhat-rpm-config and libsqlite3x-devel are the mailcatcher specific requirements
sudo dnf install redhat-rpm-config libsqlite3x-devel
gem install mailcatcher

After everything installs properly, from a terminal run MailCatcher.

mailcatcher

MailCatcher has options that you can pass it if you need to change the SMTP port or the port the web front end uses, these can be viewed by running mailcatcher --help.

Now that MailCatcher is up and running, we're ready to send it some e-mail.

Symfony

The default MAILER_URL is NULL in a Symfony project, which is rational setting that ensures that you aren't sending out emails while running a project in the dev environment (which I've done, on more than one occasion). However, there are occasions when you want to verify that an e-mail is being sent or you want to inspect the contents of that email. Symfony, of course, does provide ways through the Web Debug Toolbar to view the contents of sent e-mail and to override the intended recipient, so you aren't spamming users with dev emails (but you have to check the header if you want to see who the intended recipient was). However, I find that using MailCatcher has a more developer friendly UI and requires less configuration.

In your Symfony .env file change the MAILER_URL to point to the instance of MailCatcher.

# .env file
MAILER_URL=smtp://localhost:1025

Now all that is left to do is to point a browser to http://127.0.0.1:1080/ to see any emails that are sent from your Symfony project.

Of course, one other benefit of using MailCatcher over the built-in Symfony tools for catching dev emails is that you aren't limited to using this for just Symfony projects. You can drop this in anywhere that has a configurable SMTP url setting.

Uses

Sat, 23 Mar 2019 00:00:00 UTC

Uses

Inspired years ago by Scott Hanselman's tool list and more recently by Wes Bos' uses and prodded into action so I could make a pull request to the awesome-uses repo by Wes Bos, here is a list of the tools that I use on a daily basis:

Operating System

Fedora - currently using version 29. I've been using different flavors of Linux off and on since 2009, but after switching to Fedora (26?) in November of 2017 from Win10 both at work and at home, I haven't looked back since...

IDE's/Code Editors

PhpStorm - This is my go-to workhorse IDE - amazing to work in, not a single feature that I can think of that is missing. In fact, I have ALL of the JetBrain's IDE's on my work machine thanks to their Toolbox Subscription model, absolute best bang for your buck, IMO.
Visual Studio Code - I pull this one out when I don't need all the features of PhpStorm and want to use something a little lighter.
Sublime Text 3 - Because a carpenter needs to have more than one type of hammer in their bag, and be proficient in using them. This is another great lightweight code editor that still gets lots of use.
Eclipse BIRT Report Designer - I use this one reluctantly at work when I need to write a database report.

Terminals

Guake - I love the f12 hotkey to bring this up, so fast to fire off a quick terminal command
Terminator - If I want a more persistent terminal docked beside another window, I'll fire up Terminator

File Comparator

Beyond Compare - Nothing beats the features of Beyond Compare for file/directory comparison.
meld - Is a great free alternative

SQL Tools

DataGrip - Another great tool from Jetbrains. I'm still finding a new neat feature almost daily.
HeidiSQL - I use HeidiSQL via wine to address a couple areas that DataGrip is lacking in:
- Copying tables with or without data to a new database - I copy a lot of tables from prod to dev to develop with real data, or sometimes, I'll copy a table from dev/test to prod when I am implementing a new feature. DataGrip has implemented this recently, but it is still no where as nice as using HeidiSQL
- Creating VIEWs - this is another area where HeidiSQL beats DataGrip hands down

Notes

notion - I'd tried lots of other apps to keep notes in and nothing comes close to the power of notion. I've only scratched the surface of its flexibility, but it is still amazingly useful even only using the bare-bones features.

Hardware

Razer Black Widow Ultimate 2013 Keyboard - I wanted a mechanical keyboard with lighting and this one filled the bill. I liked it so much that I ran out and bought a second one for work after only using it at home for a week. They've served me well for almost 6 years now, but I am tempted by the sexiness of the wasd CODE keyboard. I might pick up one as a present to myself someday soon.
Sleekform Ergonomic Adjustable Office Desk Chair - I lost my Herman Miller Aeron chair in a break up, so I replaced it with this much more affordable knock off from Amazon. It's just as comfortable and durable as the Aeron, and assembly was much easier.

Music

I couldn't last a day in my office or home office without some music...

Thorens TD-166 MkII Turntable - They made everything better in the 1970s (including me) - This was my Father's Day present to myself several years ago.
Kenwood KA-8006 Solid State Stereo Integrated Amplifier - Just look at all those real knobs and switches... and it sounds great, too!
KLH AV-44 Speakers - The only part of my system made this century, but I'll give them a pass. They still can keep up with my vintage gear.

Using Conventional Commit Messages - Globally

Sun, 17 Mar 2019 00:00:00 UTC

Automating Conventional Commit Messages - Globally

I am constantly on the lookout for ways to better myself as a developer. This includes not only getting better at the actual art of coding but also improving the processes of coding and finding ways to streamline and/or automate these processes. One of the areas that I had already (mostly) improved on is writing useful commit messages, so my git log doesn't end up looking like this XKCD comic:

One bad habit that is easy to fall into as a solo developer (especially under a time constraint) is to rationalize ignoring or delaying proper documentation since you're the only one working in the codebase it is easy to think that documentation is unimportant. And it is. Until it isn't - and then it is really important.

So that is one area that I am constantly trying to improve in. A git commit message is an oft-overlooked and undervalued form of documentation, so how can we improve here? I had already been, for the most part, following The seven rules of a great Git commit message. They made sense and were easy enough to implement, and almost got me to where I wanted to be as far as git commit messages were concerned.

However, I was recently made aware of the Conventional Commits standard published by the Angular Team thanks to the Enhance your git log with conventional commits post on dev.to. I really liked the article and the standard so I bookmarked it for a more thorough reading. It was a couple of days later when I went back to the post and saw the following comment that really got my wheels spinning:

JavaScript Joel

I have added husky + commitizen + commitlint to our projects and it has been great.

Some benefits include an auto-generated change log. auto-incrementing semantic versioning. and increased visibility for breaking changes.

I would recommend it for every project.

Because we are using gitlab, we are using these packages semantic-release-gitlab and npm-publish-git-tag.

So I got to googling and found the How We Use Commitizen to Clean Up Commit Messages post that I used for a starting point on implementing and enforcing conventional commit messages.

The only problem was that the vast majority of my projects are PHP projects, and these are all npm packages. As much as I wanted to add this to my workflow, I wasn't keen on the idea of adding a package.json file to each project and adding unnecessary complexity to my dev process. So I went about discovering if these tools could be added globally so they could be added to my ~30 projects without configuring them individually for each project.

The Tools

There were three tools that I had to configure:

commitizen- Help write the conventional commit message
commitlint - Determine if the commit message is properly formatted
git global hooks - Fail the commit if the commit message is not properly formatted

Commitizen

commitizen is a handy little command line utility that provides prompts and hints for filling out each section for a conventional commit message.

The first step is to install it using npm:

npm install -g commitizen

Install your preferred commitizen adapter globally, for example cz-conventional-changelog

npm install -g cz-conventional-changelog

Create a .czrc file in your home directory, with path referring to the preferred, globally installed, commitizen adapter

echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

After commitizen has been installed, instead of making a commit with git commit you make a commit with:

git cz

This launches commitzen and you'll be prompted to first select the type of commit you are making:

After the type of commit is selected, you'll be prompted to fill out the subject, body, breaking changes, and open issues sections:

Pro-tip:

For the body (`Provide a longer description of the change:`)
If you want to add newlines you can add them with the `\n` newline character.

 
 Does a thing that is important\n\nBy doing\n-Thing 1\n-Thing 2

The dashes create a bullet list.

Yes, this is an ugly work around, but the only way that I found that works, and not a deal breaker, for me.

Now that commitizen is installed and working, we can move on to the next step.

Commitlint

commitlint is a tool that will lint your commit message and let you know if it adheres to whatever standard you've chosen.

Global installation is as easy as commitizen, but it is not explained in the readme. I had to dig around in the github issues to find an example. I plan on making a pull request to remedy this, but here are the steps:

Install the cli utility and the configuration you wish to apply:

npm install -g @commitlint/cli @commitlint/config-conventional

Create a global config file:

echo "module.exports = {extends: ['@commitlint/config-conventional']}" > ~/commitlint.config.js

That is all there to it. You can test that it is installed and working by running the following command:

echo 'should fail' | commitlint

And to see a passing message you can try:

echo "fix(server): send cors headers" | commitlint

Now we're ready to tie it all together...

git hook

commitlint in and of itself does not really do much until it is placed into a git hook. It is from inside this hook that we can fail the commit if the message does not follow the standard.

Like the earlier npm packages, I wanted this applied to all of my projects, without configuring a git hook for each individual project. If you are unfamiliar with using git hooks globally, you can check out my previous post on git global hooks.

If you've got global git hooks configured already, you can add a file as /path/to/global/hooks/commit-msg. I use the fish shell for my scripting, but the bash shouldn't look too much different. The line commitlint < $argv[1] does the work, I think bash would be commitlint < $1

#! /usr/bin/fish

# run any local commit-msg hook first
if test -e ./.git/hooks/commit-msg
        sh ./.git/hooks/commit-msg
end

commitlint < $argv[1]

exit $status

In Conclusion

So there you have it, three easy steps to set up a conventional commit message workflow. This is most useful if you can get in the habit of making atomic commits. You can see the real beauty of this after making a few commits and then running git log --one-line. Give it a shot and see what you think!

Unit Testing PHP Dates and Times with Carbon

Sat, 09 Mar 2019 00:00:00 UTC

Unit Testing Dates and Times with Carbon

One area of my codebase at work that I had problems sufficiently testing were instances in my code base that had time based logic to them. Since I work in the manufacturing sector, lots of logic relies on knowing what the current, last, or next shift is. There are lots of edge cases that need tested around shift change, especially third shift, which starts before midnight, but for all the reporting and other facets of my software it is technically tomorrow.

So these time-dependant functions for the most part did not have useful, functional unit tests, until recently. In the past I would write my logic, cross my fingers and wait for the bug reports to come rolling in. I'm so thankful that I discovered this testing aid built in to the Carbon PHP library. (If you haven't used Carbon, stop reading and go check it out, I'll forgive you. It makes working with dates and times in PHP a walk in the park, it is one of the most useful libraries I use!)

So now you are wondering, "What is this wonderful function that will let me test my date/time based logic easier?" I'm glad you asked. It is the setTestNow() function built in to the Carbon api. Basically, this allows you to determine when now() is.

// instantiate a carbon object equal to '2019-01-06 23:15:00)
$testDate = Carbon::create(2019, 1, 6, 23, 15);
Carbon::setTestNow($testDate);

$date = new Carbon();
// $date = '2019-01-06 23:15:00'

The great thing is that this now() persists across other classes, allowing easy time-based unit testing.

<?php

namespace Tests;

use App\Shift;
use Carbon\Carbon;
use PHPUnit\Framework\TestCase;

class ShiftTimesTest extends TestCase
{
    public function testThirdShift()
    {
        $testDate = Carbon::create(2019, 3, 8, 23, 15);
        Carbon::setTestNow($testDate);
        $shift = new Shift();

        $this->assertEquals(3, $shift->getCurrent());
    }
}

Discovering this helper has allowed me to add tests to lots of previously untested areas of the code base, and allowed me to get away from PDD (Prayer Driven Development).

Creating an RSS Feed for a Symfony Blog

Sun, 03 Mar 2019 00:00:00 UTC

Creating an RSS Feed for a Symfony Blog

Introduction

One of the features I've wanted to add to this blog for a while now, but kept putting off, until now, is an RSS feed. I recently created an account on connect.symfony.com and there was a spot to add an RSS feed to one's profile, which was the only thing stopping me from getting my profile to 100% and earning the "Profile completed" badge. Nothing like a little gamification to make me stop putting off this task.

Since I'm never one to re-invent the wheel, without justification, I of course looked to see if there were any Symfony bundles that would allow me to easily add an RSS feed to my blog. "Easily" being the keyword in that sentence. I did find several of bundles, but all of them seemed to have convoluted configuration, with a learning curve much steeper than rolling my own.

Oh, yea, you can see it in action here: https://eidson.info/rss

Rolling My Own

So, with a mission in hand I headed over to my google machine. The first handful of hits showed an implementation using PHP's XMLWriter, which is probably the 'right' way to do it, and would have been the better choice, if the XMl I needed to generate was any more complex than it was, but it seemed like overkill for such a simple string. Luckily, I stumbled across a post on talkerscode which gave me a good starting point.

Generating the XML

The first class that I created was a class to create my xml string that I wanted to return as my response (shown below). It is basically a simple static function that takes an array of posts and creates a properly formatted XMl string creating an item element for each post. When I tried to run this, the first couple of posts were handled properly, and then it choked and died. It turns out that the title of one of my post's contained an ampersand ('&'), which is not handled correctly by an xml parser, So I created a little helper function to escape any characters that were going to through the XML parsers for a loop.

<?php

namespace AppBundle\Rss;

class Xml
{
    public static function generate($posts)
    {
        $xml = <<<xml
<?xml version='1.0' encoding='UTF-8'?>
<rss version='2.0'>
<channel>
<title>Todd Eidson's Programming Blog</title>
<link>https://eidson.info</link>
<description>Programming Blog</description>
<language>en-us</language>
xml;
        foreach ($posts as $post) {

            $title = self::xmlEscape($post->getTitle());
            $url = self::xmlEscape($post->getUrl());
            $slug = self::xmlEscape($post->getHtml());
            $pubDate = $post->getPublished()->format('D, d M Y H:i:s T');
            $xml .= <<<xml
<item>
<title>{$title}</title>
<link>https://eidson.info/post/{$url}</link>
<description>{$slug}</description>
<pubDate>$pubDate</pubDate>
</item>
xml;
        }
        $xml .= "</channel></rss>";

        return $xml;
    }

    private static function xmlEscape($string) {
        return str_replace(array('&', '<', '>', '\'', '"'), array('&amp;', '&lt;', '&gt;', '&apos;', '&quot;'), $string);
    }
}

Creating a Controller

So now that I had the XML generation working smoothly, I needed a way to handle an incoming request and return the appropriate response, which consists of the Content-Type: text/xml; header and the XML string. So I was able to create a Symfony controller that fetched the posts, created a response, set the headers, added the XML content, and returned the response.

<?php
namespace AppBundle\Controller;

use AppBundle\Rss\Xml;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class RssController extends Controller
{
    /**
     * @Route("/rss", name="rss-feed")
     *
     * @return \Symfony\Component\HttpFoundation\Response
     */
    public function rssAction()
    {
        $posts = $this->getDoctrine()
            ->getRepository('AppBundle:Post')
            ->fetch();

        $response = new Response();
        $response->headers->set("Content-type", "text/xml");
        $response->setContent(Xml::generate($posts));
        return $response;

    }
}

Conclusion

Now I had my rss feed up and running, I was able to get my connect.symfony.com profile to 100%, earn a badge, and scratch "create an RSS feed" off of my to-do list. There are a couple improvements that could be made. When I get more than 15 or 20 posts, I'll probably limit the response to the last 10 or so posts, and if I ever start to get a lot of traffic, I'll probably cache the XML and only update it when a new post is added, but remember kids, "premature optimization is the root of all evil"!

Thanks for reading. Feedback and/or questions are always appreciated!

Override a trait in PHP

Sat, 23 Feb 2019 00:00:00 UTC

Override a trait in PHP

I encountered a situation recently in which I wanted to change the method signature for a method that was injected into a class via a trait, namely changing the default parameter. I wanted to do this so I didn't have to pass in the new default parameter every place that I called this method on this particular class.

Overriding the method, was easy enough. As soon as a new method is declared in a class with the same name, the trait method is overridden. The tricky part was calling the 'parent' method from the 'child' method, so I didn't have to duplicate the logic inside my new method. I tried parent::methodName() and TraitName::methodName() before running off to the google machine to learn the proper way to do this.

It turns out that it is as easy as creating an alias for the trait method name in the "Use" statement, which made perfect sense after I saw it.

So, if this is the trait that you want to use and override:

trait SomeTrait {
    public function someMethod(string $key = 'Id')
    {
        // logic
        return $resultOfLogic;
    }
}

Just give an alias to the trait method name when "Using" the trait as such:

use SomeTrait {someMethod as public traitSomeMethod;}

Here is a full example:

<?php

class Something
{
    use SomeTrait {someMethod as public traitSomeMethod;}

    public function someMethod(string $key = 'Name')
    {
        return $this->traitSomeMethod($key);
    }
}

So now I could call this method on any instantiation of this class without explicitly passing the default $key every time I needed to call it. Also, I had the added benefit of not having to duplicate the logic, keeping things DRY and ensuring that any changes made to the traits logic would 'bubble down' to the concrete implementation of the class.

Global Hooks with git

Sun, 17 Feb 2019 00:00:00 UTC

Global Hooks with Git

Introduction

Recently I began to wonder if there was a way to have a collection of git hooks that could run on all of my git projects to save me the trouble of creating/editing hooks in each of my projects. Yes, it is possible to do this for new projects, via the git config --global init.templatedir command, but I have a lot of pre-existing git projects that I wanted to add a pre-push hook to, and I wanted to be able to make alterations to this hook after the fact that would affect all my projects. Apparently, I'm not the only person who needed this feature, because it was added in git release 2.9.

Details

Adding the global hooks was easy enough, thanks to this stackoverflow answer, but I did run into a couple of caveats after I had the global hooks path set.

git config

To add the path to your global git configuration run the following command:

git config --global core.hooksPath /path/to/my/centralized/hooks

Hook file

The next step is to add your hook file and make it executable.

touch /path/to/my/centralized/hooks/pre-push
chmod a+x /path/to/my/centralized/hooks/pre-push

And then add what ever logic you'd like the hook to execute. I use sonarqube to provide Continuos Inspection to my projects, so I wanted the sonar-scanner to run on every push. (I highly recommend sonarqube for keeping bugs and code smells out, you should check it out if you're not familiar with it!). I use the fish shell, so you might need a different shebang.

# /path/to/my/centralized/hooks/pre-push
#! /usr/bin/fish

command sonar-scanner

So I created my hook and did a test push, to see that it worked as expected. However, I do have some documentation only and small script projects that don't use the sonar-scanner. I was getting some ugly error messages when pushing these projects. It didn't fail the push, because I wasn't checking the return code on sonar-scanner command, but I still wanted to silence these messages, or not run sonar-scanner at all on projects that didn't need it. That was easy enough to do by checking for the presence of the sonar-project.properties file before running the scanner.

# /path/to/my/centralized/hooks/pre-push
#! /usr/bin/fish
if test -e ./sonar-project.properties
    command sonar-scanner
end

Ok, so now that is running only when it should, but I bumped into another issue. I had some projects that had project specific pre-push hooks that I expected to still be running before a push was executed. I had assumed that adding these global hooks would be in addition to the project hooks, not overriding them. However, that is not the behavior I was wanting; I still wanted any project specific hooks to be executed. The fix for this was to check for the existence of a project level git hook and fire it if it exists. I decided it would make more sense for my use case to fire it before the global hook logic was executed.

# /path/to/my/centralized/hooks/pre-push
#! /usr/bin/fish

if test -e ./.git/hooks/pre-push
    command sh ./.git/hooks/pre-push
end

if test -e ./sonar-project.properties
    command sonar-scanner
end

Conclusion

So there I had my global hook, that only ran the sonar-scanner if it was necessary and made sure to also execute any local hooks. I'm sure I've only scratched the surface of the power of this, and I'm looking forward to adding more functionality in the very near future. I'm going to investigate failing the push if the sonarqube quality gate fails, next. To improve my CI/CD work flow. Have any suggestions or ideas for better hooks? Please leave them in the comments below.

Version Bump for git using Fish Shell

Sun, 10 Feb 2019 00:00:00 UTC

Version Bump for git using Fish Shell

Intro

One feature that I really like from npm is the version command which handles bumping either patch, minor, or major version number following the Semantic Versioning standards. This sets the version attribute in your package.json file and creates a git tag using the new version number.

For example you can run the npm version minor command from the root of an npm project and it will change the version from 1.2.12 to 1.3.0 write this out to your package.json file and create a git tag for the new version.

Since the vast majority of my projects are php projects and not npm, I don't get a chance to use this feature nearly as much as I would like, so I found myself wishing there was a way to do this directly from git.

Details

I have been a big fan of the fish shell since first learning about it on syntax fm's "The Command Line for Web Developers" episode, mostly for the autosuggest and autocomplete features, but more recently I've discovered the powerful scripting features. So I decided to see if I could implement this functionality through the command line via a fish script.

So basically what I wanted to do was to write a script that would read the current git tag, break it down into major, minor, and patch variables, increment the correct element, reassamble it into major.minor.patch format and create a new git tag. Once this was working I realized that if the major or minor version was incremented I needed to reset the following elements to zero. After that was worked out, I thought that I could save myself another step if it went ahead and pushed the new tag to my remote repo.

At first I had it working with a custom function name, so from the root of my repo I could type git_version minor and the new tag was calculated, created, and pushed. However, I don't personally like typing underscores, if I don't have to. So I wondered if I could "override" the git command and look for my custom command and then call git with the command line arguments, if it didn't see my custom version command. That way it would feel like a more natural extension to git. That is when I came up with this solution:

# ~/.config/fish/functions/git.fish
function git

    if count $argv > /dev/null
        if [ $argv[1] = 'version' ]
            git_version $argv
        else
            command git $argv
            return $status
        end
    else
        command git
        return $status
    end

end

This worked beautifuly. If git version minor is ran from the terminal, it calls my custom git_version function and passes the arguments to it, if anything other than version is passed as the first argument, it hands it off to git to handle. Of course, this can be altered to add many more custom commands to git, I'm looking forward to adding more functionality in the future.

And here is the custom function that is called if the version argument is passed to git. I'm sure there is room for improvements, but the few dozen times I've used it so far it behaved as expected. It expects an argument of either 'major', 'minor', or 'patch' to determine which element to bump, with an optional build argument of alpha or beta which will append a -alpha or -beta to the tag. There is also a --force flag which will create and push the tag even if there are uncomitted changes on the branch. The other flag is a --dry flag, if you just want to see the outcome of the command without creating a tag. Lastly, just running git version will display the current version.

# ~/.config/fish/functions/git_version.fish
function git_version
    set dry false
    set build ''
    set type ''
    set force false
    getopts $argv | while read -l key value
        switch $key
            case _
                switch $value
                    case major minor patch
                        set type $value
                    case alpha beta
                        set build $value
                end
            case d dry
                set dry true
            case f force
                set force true
            case v version
                _git_print_version
                return 0
            case \*
                # Handle unknown flags here
                echo unknown flag $key

        end
    end

    set v (git describe --abbrev=0 --tags 2>/dev/null)

    if [ $status != 0 ]
        set v '0.0.0'
    end

    # strip any thing from the hyphen after to remove -alpha or -beta
    set v (string split "-" -- $v)[1]
    set vmajor (string split "." -- $v)[1]
    set vminor (string split "." -- $v)[2]
    set vpatch (string split "." -- $v)[3]

    if [ $type = 'patch' ]
        set vpatch (math $vpatch + 1)
    else if [ $type = 'minor' ]
        set vminor (math $vminor + 1)
        set vpatch 0
    else if [ $type = 'major' ]
        set vmajor (math $vmajor + 1)
        set vpatch 0
        set vminor 0
    else
        echo $v

        return 0
    end

    if [ $build ]
        if [ $build = 'alpha' ]
            set build alpha
        else if [ $build = 'beta' ]
            set build beta
        else
            echo "The 'build' can only be blank, alpha, or beta"
            return 1
        end
        set tag $vmajor.$vminor.$vpatch-$build
    else
        set tag $vmajor.$vminor.$vpatch
    end

    if $dry
        echo $tag
    else
        if git_is_dirty
            if $force
                echo 'Forcing new version'
            else
                echo 'git is dirty - must use --force'
                return 1
            end
        end
        git tag $tag
        git push origin master --tags
    end
end

function _git_print_version
    echo git verison bump 1.2.0
end

Conclusion

Granted, this only works for a specific work flow, and the keystrokes it saves are negligible, but it was a neat learning experience and now I am ready to tackle some more fish scripting to make my life easier.

If you are interested in using this, it can be installed via fisher:

fisher add eidsonator/fish-git-version

The source code is available on github at fish-git-version and pull requests are welcome, if you see any room for improvement.

Please leave a comment if you can see any cons to me overriding git like this, or if you have any custom fish scripts you'd like to share.

Alphabetize your Way to More Readable Code

Sun, 10 Dec 2017 00:00:00 UTC

Alphabetize your Way to More Readable Code

Super short and simple post this time, because it's explaining a simple concept. The concept is so simple, that I'm slightly embarrassed, almost shocked, that it took me almost 7 years of professional programming, and 3 and a half years of college to see and use this pattern.

The tip? Any time you are writing code and the order of the lines is irrelevant, such as declaring class variables, creating a JSON object, populating an associative array, adding dependencies, configuring your configuration, ad infinitum, use alphabetical order.

Instead of:

{
  name: "Marshall Mathers",
  palms: "sweaty",
  knees: "weak",
  arms: "heavy",
  nervous: true,
  sweater: "mom's spaghetti"
}

Use this:

{
  arms: "heavy",
  knees: "weak",
  name: "Marshall Mathers",
  nervous: true,
  palms: "sweaty",
  sweater: "mom's spaghetti"
}

Sure, it does not rhyme as well, but if you need to change nervous to false, it is much easier to find in the list. It does take a little extra brain power to add an item to the list, instead of just appending to the list, you may have to sing a phrase of the alphabet (unless you have a tool that sorts for you, see below). However, since code is read at an average of 10 times after it is written, you'll see the pay off when looking through a long JSON object or associative array to alter or fix something.

I used to try and use some sort of hierarchical order with grouping in most places that I use this now, but there is no real hierarchy in most places that this can be implemented. Take for an example a 'person' object or class. Sure, 'name' is pretty important and would always go first (if not a uid), but how do you order the rest of the fields? Is a phone number more or less important than an address? As far as packages and dependencies go, one package might be used a lot more than another package, but I'd argue that one is no more important than the other. If it wasn't important, it wouldn't be a dependency. In fact, it was when I started a new Symfony project a few months ago and noticed that they had added "config": {"sort-packages": true} to composer.json and the profound effect that it had had on the readability of the "require" section as to what packages I was using in a project that I it had dawned on me that I should be using alphabetical order in as many places as I could to improve readability.

It wouldn't really feel like one of my blog posts if I didn't somehow mention my favorite IDE, PhpStorm, so here it is: I've recently discovered a plugin, called Lines Sorter by Sylvain Francois, that will do your sorting for you. After you have the plugin installed, highlight the lines you wish to have sorted and then in the menu go to Edit>Sort Lines or use the keyboard shortcut alt + shift + L (I had to unmap this shortcut from the default 'Load Context' option, first). This plugin will work in any of the JetBrains IDEs.

Is this something you've been doing for years? Do you have any tips that are so simple you can't believe how long it took you to incorporate them? Do you know of a VS Code plugin to accomplish this? Any arguments against using this tip? Please let me know in the comments.

filter_var() is Your Friend

Mon, 04 Dec 2017 00:00:00 UTC

filter_var() is Your Friend

Intro

I was recently reading a blog post by Aaron Saray called In PHP, False is Sometimes True. This is an issue that I've encountered in the past and I'd already considered blogging about the solution, which is something Aaron left out of his blog post.

The Issue

I'm sure that almost everyone that has dealt with handling html form data on the backend from a $_POST or a $_GET variable via http or a JSON string has encountered a situation in which trying to use a boolean value resulted in the strange behavior of "false" equaling true. This happens because when casting a string to a boolean, any non-empty string evaluates to true.

Mr. Saray used the following code snippet to demonstrate this "phenomenon".

$flag = "false";
assert((bool) $flag === true);

Of course, the assetion here returns true, because "false" IS true.

The Solution

In the past, before I learned about the filter_var function I would do something like assert($flag === "true"); This solution is perfectly valid, however, it is also perfectly inflexible. If we want to support multiple frontends, some which may actually send a boolean, or some that may use a 0 = false and 1 = true schema, this will fail and leave us hunting bugs again.

Introduced in php 5.2 and still valid in php 7+, filter_var() is the best way to tackle this problem. filter_var takes 3 arguments, the variable to filter, the type of filter to use and optional filters, which are dependent on the type of filter.

Using a filter type of FILTER_VALIDATE_BOOLEAN will return true for 1, "1", true, "true", "on" and "yes". Any other value will return false. So this solves the inflexibility issue that arrises with my 'old' solution.

Solving the above bug with filter_var would look like this:

$flag = "false";
$boolFlag = filter_var($flag, FILTER_VALIDATE_BOOLEAN);
assert($boolFlag === true);

Conclusion

I've demonstrated that using filter_var with the FILTER_VALIDATE_BOOLEAN filter type is much more predictable than simply casting the variable, and much more flexible than a hard coded solution. However, as implied by having a 'type' parameter in the filter_var function, you can do more than just safe boolean casting with this function. Two of my other most used filter types are FILTER_VALIDATE_EMAIL and FILTER_VALIDATE_IP which do pretty much as their names imply. If the variable is a valid email or IP address, they will return the variable, if not they return false. These are super useful in if statements, so throw out those long confusing regular expressions that you googled that miss edge cases anyway and start using filter_var. You can find a list of the other Validate Filters here. There are also Sanatize filters that will return an altered variable, so you can sanitize your inputs. Last but not least, check out filter_var_array() If you have an array of flags, email or IP addresses that you need to validate in one fell swoop.

Create a File Watcher for php-cs-fixer in PhpStorm

Thu, 30 Nov 2017 00:00:00 UTC

Create a File Watcher for php-cs-fixer in PhpStorm

Intro

This is a quick an easy guide to setting up a file watcher on PhpStorm so that every time a php file is saved, php-cs-fixer is ran on the file. More than just a linter, php-cs-fixer will update your code to match coding standards such as the official PSR-1 and PSR-2, as well as community standards such as the Symfony one. It will also do some modernization and micro-optimizations.

Steps

Install php-cs-fixer

There are a few different installation options, but the Composer install seemed like the easiest (like it always does). If you don't have composer installed you can follow the link above to install it. After Composer is installed, from the terminal run:

$ composer global require friendsofphp/php-cs-fixer

After it installs you can try and run it from the terminal.

$ php-cs-fixer --help

If it doesn't run, it'll need added to the path. Here is a linux command, my Windows box worked out of the box. I'm assuming the Composer Windows installer handled this for me.

$ export PATH="$PATH:$HOME/.composer/vendor/bin"

Create the PhpStorm File Watcher

From inside of a project in PhpStorm, open up the settings page. From the menu go to File > Settings or use the keyboard shortcut ctrl+alt+s (in Windows or linux).

From there you can start typing 'file watcher' to narrow down the options and then select File Watchers from under the Tools tab.

Next either press alt + insert or press the green plus sign icon in the upper right-hand corner to create a new file watcher.

Choose the Custom Template option.

In the dialog box that opens, give your watcher a name, I chose "php-cs-fixer", for the sake of simplicity.

Set the File type to "PHP" and Scope to "Current File".

Set the Program to "php-cs-fixer". In my Windows environment, I had to add the '.bat' file extension (example below). In my linux environment I had to use the full path to my ~/composer/vendor/bin/php-cs-fixer (example above). Run which php-cs-fixer from the terminal to get the full path. This command works on Windows 10, too.

The Arguments is where all the work is done. First type fix which is the command for php-cs-fixer to actually do something. Next add any flags you want to pass in for the rules. Finally add $FilePath$ which is a PhpStorm variable for the full path to current file, up to and including the name and extension.

Set the "Output paths to refresh" to $FilePath$ so the editor reload the current file as soon as the changes are saved.

The final step and a very important one is to uncheck the "Auto-save edited files to trigger the watcher" checkbox under "Advanced Options." If this is checked, the watcher will run with each keystroke in the file editor and PhpStorm will become confused if the memory (editor) changes or the disk(php-cs-fixer) changes are the ones to use. If you are still on PhpStorm 2017.2 this option is labeled "Immediate file synchronization".

Click "OK" to save your file watcher, and then close the settings dialog.

Conclusion

Setting up this file watcher in PhpStorm is super easy and crazy useful.

Another option would have been to use the external tools option of PhpStorm, which is the original way I was going to do this, inspired by a Laracasts tutorial. The only downfall to using php-cs-fixer as an external tool, is that you have to manually trigger it. I wanted php-cs-fixer to be a fully automated step in my work flow.

One more, fully automated, way to integrate php-cs-fixer would be to use a git pre-commit hook. I still like the file watcher option better, because it allows me to see in the editor if there are still warnings from other linters and sniffers if there are things that could still be improved even after php-cs-fixer is ran.

php 7.3 - Flexible heredoc & nowdoc Syntax

Sun, 26 Nov 2017 00:00:00 UTC

php 7.3 - Flexible heredoc & nowdoc Syntax

Although we've still got a while to go before we see php 7.3, since we're still 4 days away from the release of php 7.2, I've already seen one new feature that looks like it will make its way into 7.3 that I am excited about. This feature is more flexible syntax for heredoc and nowdoc statements. Here is the official rfc if you'd like to read it.

What are heredocs and nowdocs?

Heredocs and nowdocs are the easiest and cleanest ways in php to use and format multiline strings.

Instead of:

$html = '<ul>';
$html .= '<li>item 1</li>';
$html .= '<li>item 2</li>';
$html .= '<li>item 3</li>';
$html = '</ul>';

We can use:

$html = <<<html
<ul>
    <li>item 1</li>
    <li>item 2</li>
    <li>item 3</li>
</ul>
html

The only difference between a heredoc and a nowdoc is that a heredoc performs string interpolation, turning your variables into the string they represent, while a nowdoc does not.

//heredoc example
$name = 'Todd Eidson';
$text = <<<txt
My name is $name
txt

echo $text;
// outputs 'My name is Todd Eidson'

//nowdoc example
$name = 'Todd Eidson';
// notice the single quotes around the marker 
$text = <<<'txt'
My name is $name
txt

echo $text;
// outputs 'My name is $name'

One great thing about using a heredoc/nowdoc within a good IDE (like my favorite, PhpStorm) is that php allows you to pick your own heredoc marker, and PhpStorm is smart enough to give you syntax highlighting inside the heredoc based on the marker used. For example if you use sql or HTML for your marker name, your heredoc string will use the code highlighting of the marker, making mistakes easy to spot.

Caveat

The only caveat (for now) when using a heredoc/nowdoc is that the end of statment marker must be the first and only thing on the line. This leads to left aligned text in the middle of a function or method that can be quite jarring when quickly scanning code, much like coming to a stop sign in the middle of an interstate, your brain has to slow down for a second to figure out why your indentation is not being properly followed.

Like so:

class MyClass
{
    public function MyFunction($variable)
    {
        if ($variable) {
            $html = <<<html
Why is this code against the left margin?
It would be really nice if it was
properly indented.             
html
        }
        return $html;
    }
}

The Changes

In php 7.3 we will be able to indent the end of heredoc marker to improve readability. Any whitespace before ending marker will also be stripped off the front of the each line in the multiline string. Any line that is not indented to at least the level of the ending marker will throw an error.

An example:

class MyClass
{
    public function MyFunction($variable)
    {
        if ($variable) {
            $html = <<<html
                Isn't this so much easier to read?
                It is really nice that it is
                properly indented.
                And so much easier to read!             
                html
        }
        return $html;
    }
}

The other chage is that the ending marker does not have to be followed by a new line. I can't remember a time at which I wished for this ability, so I'm not nearly as excited about this as I am the ability to indent the ending marker, but I'm sure some people will get some use out of it. I guess it could be useful if using multiple heredocs in a function call or an array.

Like this:

// The old way:
myFunction(<<<txt
This is
the first parameter
txt
, <<<txt
This is
the second parameter
txt
);


// The new way
myFunction(<<<txt
This is
the first parameter
txt, <<<txt
This is
the second parameter
txt
);

Conclusion

I'm really looking forward to when I can get switched over to 7.3 (or 8, whichever comes first) so I can take advantage of this new feature and clean up all my heredocs. I do recommend reading the rfc as there are some nuances concerning marker names and a raised backwards incompatability issue that I don't go over in this post.

What are your thoughts on this change? Yay, nay, or meh?

The Joy of Rotating Logs in Symfony

Fri, 24 Nov 2017 00:00:00 UTC

The Joy of Rotating Logs in Symfony

Switching from my hand-made, hodgepodge, cobbled together collection of libraries that was trying to act more and more like a "framework" every day to a full-blown real, properly developed, properly tested framework like Symfony continues to be the best decision I've made in my programming career thus far. I've learned so much about clean code, design patterns, SOLID principles and many other programming best practices from working within Symfony's MVC (Model View Controller) pattern and reading its documentation and code when I need to extend it to bow to my every whim.

One great feature of Symfony is the highly configurable logging, implemented via monolog.
Way back in my pre-Symfony days, when I encountered an exception in development, my first step was firing up xdebug and stepping through the code line by line to inspect variables and watch where the logic was taking me to try and find the root cause of the bug. Now my first step is to head to the log file and see what was happening at the time of the exception (for JSON calls, anyway. The log is spit out on the screen if the result of the call was to render a page).

I prefer text logging verses logging to a database, for the simplicity of writing and reading.
One problem with text logging is that the files can grow too big, too fast. Most text editors will choke on a log file that is too big. Or, the worst case scenario may be encountered, which is the log file becomes so large that it eats up all available disk space on the server, bringing the server to its knees. Thankfully I've only encountered this once, due to leaving a debug flag on in production. Which brings up another great thing about using Symfony, thanks to the app_dev.php file, no more debug flags.

To combat the issue of log files growing too large, one of the first things I do in any new Symfony project is to set the log type to rotating_file which is a standard feature in monolog, but beautifully exposed via the Symfony configuration file.

This can be set in both your prod and dev config files, to give the desired behavior for each environment.

Development

In the config_dev.yml simply change the main handler type from stream to rotating_file and just below that add the max_files to keep. I set mine to 1 in dev, since I don't believe that a development log file needs to persist past a single day. Voilà, a fresh clean log file every morning when I access my log in the development environment.

# app/config/config_dev.yml
monolog:
    handlers:
        main:
            # change this line
            type: rotating_file
            # add this line
            max_files: 1
            path: '%kernel.logs_dir%/%kernel.environment%.log'
            level: debug           
            channels: ['!event']
        console:
            type: console
            process_psr_3_messages: false
            channels: ['!event', '!doctrine', '!console']
        # To follow logs in real time, execute the following command:
        # `bin/console server:log -vv`
        server_log:
            type: server_log
            process_psr_3_messages: false
            host: 127.0.0.1:9911

Production

In your project's production environment configuration file - config_prod.yml, we'll make the same changes, but under the nested handler. The nested handler is another great aspect of logging with monolog from inside of a Symfony project. If the main handler is set to a fingers_crossed type, it caches the log for every request. The only time that it logs anything, is if the action_level threshold is passed. In the example below, if a log level of error or higher is caught, it passes the cached log to the handler set in the handler parameter. This allows logging of the full request stack, but only in the event that an error occurs. This way only meaningful logs are stored, but we get the entire log for that request. This is another feature that keeps are logs from growing too large.

# app/config/config_prod.yml
monolog:
    handlers:
        main:
            type: fingers_crossed
            action_level: error
            handler: nested
        nested:
            # change this line
            type:  rotating_file
            # add this line
            max_files: 7
            path:  "%kernel.logs_dir%/%kernel.environment%.log"
            level: debug           
        console:
            type: console
            process_psr_3_messages: false

Log files location

Another thing I like to do with the logging, is change the location of where my log files are stored. By default, the log files are stored in project_root/var/logs. My deployment process creates each new release in a releases directory in my production environment, and my webroot is nothing more than a symlink that that points to the most recent releases directory. If I keep the default log file location, each release uses its own directory to store log files. By moving the logs directory up one level, each release uses a shared log location so my log files persist across new releases of my project. Another benefit to this is not having to worry about setting write permissions for the www-data user that Apache uses for the log directory in each new release. It is easy to alter the getLogDir() method in your AppKernel class to use one level up, or any other custom location in which you wish to store your log files.

    // project_root/app/AppKernel.php
    public function getLogDir()
    {
        // I've inserted the '../' to move the logs up one directory from the project root
        return dirname(__DIR__).'/../var/logs';
    }

Easy log file viewing

As easy as it is to view log files in development, to logs in your production environment, you have to log in to your production server, navigate to the log directory and then open them with the log viewer/text editor of your choice. It was those couple extra steps that inspired me, after not finding any existing solutions that I liked, to write a Symfony bundle that allows you to view your logs from your web browser.
My WebLogViewerBundle includes color-coded, collapsable log levels, and formatted JSON and SQL. It can be included via Composer (packagist) and the source can be found on GitHub.

Conclusion

Hopefully, you can see the benefits and ease of using rotating log files in your Symfony projects. How do you configure your logging in Symfony?

Editing Shared Libraries in PhpStorm with Composer and git

Sun, 19 Nov 2017 00:00:00 UTC

Editing Shared Libraries in PhpStorm with Composer and git

The "Old" Workflow

When I started my current position way back in the winter of 2013 as the sole Application Developer in a corporate/enterprise environment, I was tasked with maintaining existing web applications, porting Visual Basic apps into a web environment, as well as creating new applications. Each of the php applications that I had inherited had several shared dependencies that were maintained independently in their separate project directories. Any bug that was found and fixed in one of these 'libraries' had to be copied manually to the other projects that were using this library. Seeing this as a clear violation of the DRY (don't repeat yourself) principle, I decided to move the libraries into a central location that could be shared among the different projects via the php include path. This approach worked fine, until I wanted to start introducing changes that broke backwards compatibility for the benefit of one project. It would break the other projects until they had been updated to use the newer version of the library. (I was still using manual deployment, no unit testing, no frameworks, it was a dark and dreary time.)

Take Two

It was about this time that I realized that it would indeed be best to keep individual copies of the libraries with each project, to prevent the aforementioned problems with backwards compatibility breaking changes, but these libraries needed to be managed from a central location. I had recently convinced my manager that we should switch from svn to git, and I thought that maybe using git-submodule would be the answer to the question of how to manage these dependencies. It wasn't. It was messy. It was broken. It was the worst idea I had had in a long series of bad ideas in trying to tackle this problem. It was also about this time that I had realized that what I was trying to do was write my own framework. I had a database connection library, a library that auto-wired my templating engine, an ldap connection library... I needed to stop trying to reinvent the wheel and just learn and use a real framework.

Composer to the Rescue

I decided to learn and implement the Symfony Framework. Learning Symfony included learning about Composer which I was vaguely familiar with, but totally unaware of how powerful it is. In hindsight I should have realized that a "Dependency Manager" was exactly what I needed to manage my dependencies. I soon learned that I could include my own repositories in my projects via the Composer configuration. Using this I could make changes to my library inside of my project, copy these changes to my library repository, upload the changes to my central repository and then get the changes in my other projects by using composer update. This was a couple extra steps than I wanted to take, but it was the workflow I had been looking for all along.

Composer, git, and PhpStorm

I soon realized that when one includes a repository with a type of 'vcs' through composer, you not only get a copy of the files in that project, you get a copy of the entire repo, up to and including the .git directory. So basically I could make changes to my repo from inside of my vendor directory and commit and push to my central repository straight from there. When I learned that I could inform my favorite IDE PhpStorm about these 'sub' repositories and commit and push directly from the user interface my current workflow was concreted and perfected (for now).

Steps to implement this process

In the project's composer.json file add a repositories section pointing to your shared library.
Add your repository as a dependency in the require section
- This will also work if use satis to require your repositories

{
    "repositories": [
        {
            "type": "vcs",
            "url": "git@github.com:greenskies/WebLogViewerBundle.git"
        }
    ],
    "require": {
        // other dependencies
        "greenskies/web-log-viewer-bundle": "dev-master"
    }
}

Open up the settings in PhpStorm via File > Settings or ctrl + alt + s (in Windows or Linux)
Click on the Version Control tab

Click on the green + (plus sign) in the upper right hand corner of the dialog to add another vcs path
Add the path to your library inside of your vendor folder - PhpStorm should select the git vcs type for you

Now, anytime you make any change to your shared library, you can select "git > Commit file" or "Commit Directory" to commit and push your changes! (You can also use git from the command line/terminal from inside of shared library to commit & push)

Do you have any tips and tricks to integrate git, Composer, and PhpStorm into your worklow? If so, please share them in the comments.

PHP_EOL is Broken (Sometimes)

Sun, 12 Nov 2017 00:00:00 UTC

PHP_EOL is Broken (Sometimes)

What is PHP_EOL?

Introduced in version 5.0.2 of php, PHP_EOL is a string constant that represents the correct end of line symbol for the platform that you are running php on. So on Windows this should be set to "\r\n" (carriage return and line feed) and on a *nix system it should be set to "\n" (only line feed).

Where is it Used?

You SHOULD use it when programmatically creating a text file via php.

$text = 'Line one' . PHP_EOL;
$text .= 'Line two' . PHP_EOL;
 
$file = fopen('file.txt', 'w');
fputs($file, $text);
fclose($file);

This will create a platform correct end of line separator, and ensure portability in a project.

Okay, So How is it Broken?

Usually when one is working with strings that contain multiple lines and they want to create an array that consists of each individual line they will use:

$array = explode(PHP_EOL, $string);

However, in the last couple of weeks I've been bitten by two different bugs caused by the very simple line of code above.

Bug #1

The first was when I was working on my Web Log Viewer Bundle project which is a Symfony bundle for viewing log files created by a Symfony project online, so logging in to the server to view them in not necessary. This project parses log files, formats the lines, and displays them in an HTML table. I was using $array = explode(PHP_EOL, $string);, but when running this on a Windows box, my string was not exploding correctly and I was getting $array = [$string] instead of $array = [line1, line2, line3, ...].

Symfony uses monolog, and I didn't investigate how monolog writes its end of line symbols in an attempt to determine the root cause of this bug, but I did need to find a fix. Help me stackoverflow, you're my only hope.

Bug #2

I've recently started using Magallanes to deploy my projects, instead of my old hacky way of using a git post commit hook to push my changes to a git repo on the production server and then logging in to the production server and manually performing 5 or 6 steps to update dependencies, build assets, and clear caches. I did have to make a handful of really small changes to make it work in a Windows environment, but oh, man, was it worth it. Lots more on how I improved my deployment process with Magallanes in later posts.

I mentioned that I had to make some changes to make Magallanes work in a Windows environment, and I thought that I had everything worked out until I noticed this next bug. I use the "releases" option of Magallanes that uploads the current release to a timestamp-based-name directory inside of the releases directory and then creates a symlink named current that points to the newest directory in the releases folder. In the Magallanes config file, there is a parameter named releases that indicates the number of previous releases that should be kept on the server, in case there is a need to rollback to an earlier release. I noticed that in one of my releases directory, there were about 10 previous releases, when I had this configuration parameter set to 5. Something was broken.

I went looking through the cleanup task code and discovered that it was using ls -1 via ssh to get a string of all the directories inside of the releases directory and then using my recent archnemesis $releases = explode(PHP_EOL, trim($releases)); to turn that string into an array and doing all the work on the array. I was pretty confident that the bug was in the explode statment, due to my recent experience with Bug #1. After stepping through the code using xdebug, my hunch was confirmed, and I knew just where to find the fix.

The Fix

Some people, when confronted with a problem, think "I know, I'll use regular expressions." Now they have two problems. - Jamie Zawinski

After discovering Bug #1, I fired up my trusty google machine and went in search to a solution for this problem. Sure enough, the first search result was a stackoverflow answer that fixed the bug. It was the following simple, one-line, cross-platform fix:

Replace:

$lines = explode(PHP_EOL, $str);

With:

$lines = preg_split('/\n|\r\n?/', $str);

So, of course, I knew the perfect fix when I came across Bug #2, just a few short weeks later.

Conclusion

Although I was more concerned with fixing the bugs than I was with finding the root cause of the bugs, which would have required I solve the riddle "when is the end of line not the end of the line?", I was able to implement a nice and easy cross-platform solution and come to the conclusion that PHP_EOL is Broken (Sometimes).

Code Highlighting in HTML

Sun, 22 Oct 2017 00:00:00 UTC

Code Highlighting in HTML

I've been wanting to start blogging for quite some time now, and I figured there is no time like the present. I am familiar with both WordPress and Drupal, but I wanted to "roll my own" both for flexibility and as a learning experience. Since this blog is going to be code heavy, one thing that was really important to me was code highlighting in the display. I really like the code highlighting on the Symfony documentation pages, and I've used that in some of my own documentation pages, however, that is using Sphinx and .rst files, which requires a compilation step. I was looking for a way to have markdown files parsed by a real-time HTML converter to give me syntax highlighted code in HTML. That's how I discovered highlightjs.

highlightjs will take any code that inside of an element that has a class of {language-name}, lang-{language-name}, or language-{language-name} and wrap keywords, built-ins, and strings/numbers in spans that have highlighting classes assigned to them. There is a cdn version available that has support for 23 of the most popular languages that can be added to your project in 3 easy steps.

First add the stylesheet to the head section of the HTML page.

<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css">

Next add the JavaScript to the end of your body element.

<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>

Finally, after the JavaScript is loaded, fire off the initHighlightingOnLoad() function to add the formatting.

<script>hljs.initHighlightingOnLoad();</script>

Now that the css and JavaScript is loaded and the OnLoad function is taken care of, we can throw some code at it to be highlighted.

In a markdown file, any text that is encased in triple backticks will be treated as code upon parsing, the language can be added after the opening set of backticks. If the language is not present highlightjs will make a best guess to which language it is.

```javascript
    var s = "JavaScript syntax highlighting";
    window.alert(s);
    var num = 42;
```

The parsed HTML will appear as such. The class is derived from the language appended to the triple backticks in the above step (This will also work on raw HTML written as below, if it is not being parsed from a markdown file)

<pre>
    <code class="language-javascript">
        var s = "JavaScript syntax highlighting";
        window.alert(s);
        var num = 42;
    </code>
</pre>

The highlighted results of the parsed markdown will appear like this:

var s = "JavaScript syntax highlighting";
window.alert(s);
var num = 42;

It is really quite simple to implement this powerful code highlighting library, and if the 23 languages included in the hosted version don't cover a particular language that you need to highlight you can go to their download page to build a custom version which can include support for any of 176 different languages, which is what I'll be switching to as soon as I write my first post that requires highlighting for the twig templating language.