Posts tagged 'example'

A refactoring example

published on January 13, 2020.

I’m working on a small side project to gather stats about my blog. Posts published, words written, number of code examples. Good for practicing TDD. I want to share how I made one part of it better.

This part is a post collector that goes through a folder and collects post files. The first version of the PostCollector iterates over a path with DirectoryIterator. It finds all markdown files and creates a Post from them:

PostCollector.php
<?php declare(strict_types=1);

namespace RobertBasic\HugoStats;

use DirectoryIterator;
use Generator;
use SplFileInfo;

class PostCollector
{
    public function collectFrom(string $path): Generator
    {
        $directory = new DirectoryIterator($path);

        foreach($directory as $file) {
            if ($this->isAPostFile($file)) {
                yield Post::fromFile($file);
            }
        }
    }

    private function isAPostFile(SplFileInfo $file): bool
    {
        if (! $file->isFile() || ! $file->isReadable()) {
            return false;
        }

        if ($file->getExtension() !== 'md') {
            return false; }

        return true;
    }
}

The PostCollector works and the tests are green, but it can be better. It does too many things, breaks the Single Responsibility Principle:

  • creates a directory iterator from the $path argument,
  • iterates over the directory,
  • decides is a file a post file,
  • creates the post file.

The Post that the PostCollector creates does nothing:

Post.php
<?php declare(strict_types=1);

namespace RobertBasic\HugoStats;

use SplFileInfo;

class Post
{
    private SplFileInfo $file;

    private function __construct(SplFileInfo $file)
    {
        $this->file = $file;
    }

    public static function fromFile(SplFileInfo $file): self
    {
        return new self($file);
    }
}

Let’s improve the PostCollector. We remove the internal DirectoryIterator. Instead, we pass in a ContentDirectory which better describes the type we are working with:

PostCollector.php
<?php declare(strict_types=1);

namespace RobertBasic\HugoStats;

use Generator;

class PostCollector
{
    public function collectFrom(ContentDirectory $contentDirectory): Generator
    {
        foreach($contentDirectory as $file) {
            if ($this->isAPostFile($file)) {
                yield Post::fromFile($file);
            }
        }
    }

    private function isAPostFile(SplFileInfo $file): bool
    {
        // No changes here from the previous example...
    }

The PostContent has one responsibility less. Progress!

ContentDirectory is a DirectoryIterator:

ContentDirectory.php
<?php declare(strict_types=1);

namespace RobertBasic\HugoStats;

use DirectoryIterator;

class ContentDirectory extends DirectoryIterator
{
}

I feel like the ContentDirectory wants to be an interface though. Let’s try that:

ContentDirectory.php
<?php declare(strict_types=1);

namespace RobertBasic\HugoStats;

interface ContentDirectory
{
}

As we are getting the post files from a local content directory, let’s have that implement our content directory interface:

LocalContentDirectory.php
<?php declare(strict_types=1);

namespace RobertBasic\HugoStats;

use DirectoryIterator;

class LocalContentDirectory extends DirectoryIterator
                            implements ContentDirectory
{
}

If we keep in mind the “composition over inheritance” rule, then the extends DirectoryIterator part stands out. We can make the LocalContentDirectory a wrapper around DirectoryIterator:

LocalContentDirectory.php
<?php declare(strict_types=1);

namespace RobertBasic\HugoStats;

use DirectoryIterator;

class LocalContentDirectory implements ContentDirectory
{
    private DirectoryIterator $directory;

    public function __construct(DirectoryIterator $directory)
    {
        $this->directory = $directory;
    }
}

If we remember, we loop over the contents our of ContentDirectory in the PostCollector. A way to do it is to have our LocalContentDirectory be an Iterator as well. The iterator methods will call the methods on our internal DirectoryIterator:

LocalContentDirectory.php
<?php declare(strict_types=1);

namespace RobertBasic\HugoStats;

use DirectoryIterator;
use Iterator;

class LocalContentDirectory implements ContentDirectory, Iterator
{
    private DirectoryIterator $directory;

    public function __construct(DirectoryIterator $directory)
    {
        $this->directory = $directory;
    }

    public function current()
    {
        return $this->directory->current();
    }

    public function next()
    {
        $this->directory->next();
    }

    public function key()
    {
        return $this->directory->key();
    }

    public function valid()
    {
        return $this->directory->valid();
    }

    public function rewind()
    {
        $this->directory->rewind();
    }
}

The code looks better. We have a content directory type marked by the ContentDirectory interface. We have our local content directory LocalContentDirectory that implements the ContentDirectory interface. Internally it uses a DirectoryIterator and itself is a type of Iterator which makes it possible to loop over it.

As a final step, let’s tackle the fact that the Post does nothing, only holds a reference to the SplFileInfo object. One thing I didn’t like about the PostCollector is that it was deciding whether a file is a post or not. This is the job for the Post object. Let’s have it decide for its own whether a file is a Post or not:

<?php declare(strict_types=1);

namespace RobertBasic\HugoStats;

use SplFileInfo;

class Post
{
    private SplFileInfo $file;

    private function __construct(SplFileInfo $file)
    {
        if (! $file->isFile()) {
            throw new \RuntimeException('File is not a file');
        }
        if (! $file->isReadable()) {
            throw new \RuntimeException('File is not readable');
        }
        if (! $this->fileHasMarkdownExtension($file)) {
            throw new \RuntimeException('File does not have a markdown extension');
        }

        $this->file = $file;
    }

    public static function fromFile(SplFileInfo $file): self
    {
        return new self($file);
    }

    private function fileHasMarkdownExtension(SplFileInfo $file): bool
    {
        return $file->getExtension() == 'md';
    }
}

And now our PostCollector becomes what we wanted it to be — a collector of post files:

<?php declare(strict_types=1);

namespace RobertBasic\HugoStats;

use Generator;

class PostCollector
{
    public function collectFrom(ContentDirectory $directory): Generator
    {
        foreach($directory as $file) {
            try {
                yield Post::fromFile($file);
            } catch (\RuntimeException $runtimeException) {
                continue;
            }
        }
    }
}

For every file in our content directory, we try to create a Post from it. If we don’t succeed, then we carry on as if nothing happened, otherwise we yield the Post file for further use.

From a PostCollector that did too many things, we now have 3 things each doing their job. A LocalContentDirectory responsible for getting the files from a folder. A Post responsible for deciding is a SplFileInfo a post file or not. PostCollector iterating over the files and creating Posts out of them.

What would you do differently? Do you see room for more improvement? Let me know on Twitter or drop me an email.

Happy hackin’!

Tags: php, refactor, example, srp.
Categories: Programming, Development.

Bad Firebug!

published on December 21, 2009.

We all know about Firebug, probably the best developer add-on out there, and how awesome it is and how many times it helped us debug some nasty Javascript code, mess around with CSS and HTML on-the-fly, to track the time load of every external page element our app loads… It’s so cool that it even has it’s own add-ons! (FirePHP, YSlow and FireCookie). Really, it helps our developer lives to suck a bit less.

Note: the following text is not about bashing other developers and their works, but to highlight the importance of proper input filtering. I myself have failed on this, several times.

Let’s go back to the part where we mess with the HTML by the means of this, may I say, application. You can add, hide, remove HTML elements, add, alter, remove, attributes from HTML elements… Adding, hiding, deleting - boring; altering - fun! I have this urge to try to break every form on every website I find. Not to do any harm, just to take a look how my fellow developer did his job and if I see anything that’s not right, I try to contact him to fix that, cause, y’know, I’m a nice person… Anyhow, I recently found some sites where all the textfields and textareas were filtered properly and no harm could be done - all my “hack” attempts were caught by their application. Nice. Oh, look, a select box! Right-click, inspect element, value="xyz”, change that to value="abc”, submit the form… and poof! A sexy SQL error. All that with the help of our li’l friend, Firebug. The elements where the user is required to provide some information “by hand” were processed correctly, but the select box was not.

OK, let’s take this one step further. On a site where the user can register an account and afterwards can edit his or hers profile. I register, go to the user panel, the usual stuff - change email, password, location, DoB (Date of Birth)… A quick inspection of the source - a hidden field “id” with a number in it. Hmm… Quickly, I register another account, note the “id” on that second account, go back to the first account, change the “id” of the first account to the “id” of the second account, change the DoB (just to see any actual information changing), click submit… “Your profile has been updated successfully.” Mine? Not really, the DoB is like it was in the first place… Go to the second account… Oh boy. I successfully changed the DoB of the second account, with my first account. Now, I haven’t seen their source code, but I can imagine what was going on. Something like this:

<?php
$id = (int)$_POST['id'];
$dob = $_POST['dob'];

$sql = "UPDATE users SET dob = '" . $dob . "' WHERE id = " . $id;

On the positive side, when I entered letters in that hidden field, I was told by the app that I haven’t filled all the fields correctly, which means they filtered even the hidden field, but skipped to check if that “id” is actually me.

OK, I know, the title is “Bad Firebug!” and the problems are actually about filtering user input, but I needed a catchy title to have your attention on Twitter :P

Even tho a field seems “unchangeable”, with a help of an awesome little app, it becomes changeable. And dangerous.

Filter input, escape output :)

P.S.: On the image above you can see my profile on a bulletin board, where I changed my year of birth from 1986 to 986 with Firebug. The years are in a select box; the lowest value is 1910. You can see my actual profile here.

Chaining routes in Zend Framework

published on November 27, 2009.

On a forum, there was a question today, about adding language “support” to the routes using Zend Framework. The guy wanted routes like /en/foo/bar or /de/baz. I wrote there an example for that using Zend_Router_Routes_Chain, so just posting that example here, too :)

For what chains are for, is described in the manual, so I won’t be covering that :P

Basically, we’re prepending the language route to the other routes. This way, we have defined the route for the languages in one place only, plus, the other routes don’t have to worry about the language, too.

// this goes in the bootstrap class
<?php
public function _initRoutes()
{
    $this->bootstrap('FrontController');
    $this->_frontController = $this->getResource('FrontController');
    $router = $this->_frontController->getRouter();

    $langRoute = new Zend_Controller_Router_Route(
        ':lang/',
        array(
            'lang' => 'en'
        )
    );
    $contactRoute = new Zend_Controller_Router_Route_Static(
        'contact',
        array('controller'=>'index', 'action'=>'contact')
    );
    $defaultRoute = new Zend_Controller_Router_Route(
        ':controller/:action',
        array(
            'module'=>'default',
            'controller'=>'index',
            'action'=>'index'
        )
    );

    $contactRoute = $langRoute->chain($contactRoute);
    $defaultRoute = $langRoute->chain($defaultRoute);

    $router->addRoute('langRoute', $langRoute);
    $router->addRoute('defaultRoute', $defaultRoute);
    $router->addRoute('contactRoute', $contactRoute);
}

Assuming that we have an Index controller, with actions index and contact and a Foo controller with actions index and bar, paired with the routes from the above example, we could do requests like:

/ => /index/index/lang/en
/de => /index/index/lang/de
/sr/contact => /index/contact/lang/sr
/en/foo => /foo/index/lang/en
/fr/foo/bar => /foo/bar/lang/fr

Requesting a page like, e.g. /de/baz, would give us a 404 page, cause we don’t have a Baz controller.

HTH :)

Happy hacking!

Playing with Zend_Navigation and routes

published on August 09, 2009.

O hai. First things first - someone should slap me for being such a lazy blogger. Somehow I lost all the motivation I had in the beginning, but looks like it’s back now :) I finally had the time to play around with the latest Zend Framework version (v 1.9 now). I managed to skip the whole 1.8.x version, so this whole Zend_Application stuff is quite new to me. I spent a few days poking around the manual and the code to make it work. And it works! Yey for me! And yey for Rob Allen for his post on Bootstrapping modules in ZF 1.8!

Zend_Tool is an awesome tool. Creating a new project is like “zf create project project_name” :) And the new bootstrapping process with the Bootstrap class is somehow much clearer to me now… Anyways, lets skip to the code.

The goal

I wanted to set up routes in such way that when a user requests a page, all requests for non-existing controllers/modules are directed to a specific controller (not the error controller). In other words, if we have controllers IndexController, FooController and PageController, anything but http://example.com/index and http://example.com/foo is directed to the PageController. This can be useful for CMSs or blogs to make pretty links. Here’s where the Zend_Controller_Router_Route_Regex stuff comes in:

<?php
$route = new Zend_Controller_Router_Route_Regex(
    '(?(?=^index$|^foo$)|([a-z0-9-_.]+))',
    array(
        'controller' => 'page',
        'action' => 'view',
        'slug' => null
    ),
    array(
        1 => 'slug',
    ),
    '%s'
    );

$router->addRoute('viewPage', $route);

Basically the regex does the following: if it’s index or foo don’t match anything, thus calling up those controllers, in any other case match what’s requested and pass it to the PageController’s viewAction as the slug parameter. The fourth parameter, the ‘%s’, is needed so that ZF can rebuild the route in components like the Zend_Navigation.

Now, when the PageController, viewAction get’s called up, we can check, for example, if a page with that slug exists (like, in a database). If it exists, show the content, otherwise call up a 404 page with the error controller. In this fancy and sexy way we can call up pages without passing ID’s or even letting the user know what part of the website is working on his request. He just request’s http://example.com/some_random_article and kaboom! he get’s the content :)

Page navigation

Oh the joy when I saw Zend_Navigation in the library! And it even includes view helpers to help us render links and menus and breadcrumbs! Yey! There are a several blog posts which go in details about Zend_Navigation, so I won’t be bothering with that. What I wanted to make with Zend_Navigation is to have a menu of all the pages rendered everywhere. Here’s where action helpers kick in. I made an action helper which makes up the structure of the links/pages. Something like this:

<?php
class Zend_Controller_Action_Helper_LinkStructure extends
        Zend_Controller_Action_Helper_Abstract{
function direct(){
$structure = array(
    array(
         'label'=>'Home page',
         'uri'=>'/'
    ),
    array(
         'label'=>'Articles',
         'uri'=>'',
         'pages'=>array(array(
                                  'label'=>'Article 1',
                                  'uri'=>'article_1'),
                              array(
                                  'label'=>'Article 2',
                                  'uri'=>'article_2'),
                         )
    )
);
return new Zend_Navigation($structure);
}
}

This is a simple example of the structure; I’m actually making it out from the database, with all the categories, subcategories and pages.

Links everywhere

To have this menu on all pages, we need to render it in the layout.phtml. Rendering is quite simple:

<?php
// somewhere in layout.phtml
<?php echo $this->navigation()->menu(); ?>

Of course, we need to pass the menu to the navigation helper somehow. To avoid doing $this->navigation($this->_helper->linkStructure()); in all the controllers, we could do that once in the bootstrap (any other ways to make it happen?):

<?php
// in Bootstrap.php somewhere in the Bootstrap class
function _initView(){

        $view = new Zend_View();
        $view->doctype('XHTML1_STRICT');
        $view->headMeta()->appendHttpEquiv('Content-Type', 'text/html; charset=UTF-8');

        // our helper is in app/controllers/helpers folder, but ZF doesn't know that, so tell him
        Zend_Controller_Action_HelperBroker::addPath(APPLICATION_PATH.'/controllers/helpers');
        // now get the helper
        $linkStructure = Zend_Controller_Action_HelperBroker::getStaticHelper('LinkStructure');
        // and assign it to the navigation helper
        $view->navigation($linkStructure->direct());

        $viewRenderer = Zend_Controller_Action_HelperBroker::getStaticHelper('ViewRenderer');
        $viewRenderer->setView($view);

        return $view;
}

There. Now we have our menu rendered on all pages. Sexy isn’t it? :)

That’s it for now. Hope someone will find this useful :) Now I gotta go, need to get ready for a punk rock concert tonight!

Happy hacking!

Wordpress as CMS tutorial

published on March 14, 2009.

Wordpress is one of the best blogging platforms out there — if not the best. It’s very powerful, can be easily extended and modified. It’s documentation is very well written and, so far, had answer to all of my crazy questions :)

You know what’s the best part of Wordpress? With some knowledge of PHP and MySql, you can turn it into much more than just a blogging platform. After doing some HTML to WP work for Roger, I thought of one way how could Wordpress be transformed into a CMS. Note the “one way”. This is not the only way for doing this, and, most likely, not the best way.

I didn’t look much, but I think that there are some nice plugins out there that can do this. But, where’s the fun in the download, upload, activate process? Nowhere!

I will show you how to change your Wordpress into a CMS and it really doesn’t take much coding to achieve this! The example presented here is simple and will have a static page for it’s home page, another static page for the “Portfolio” page and the blog. The home and portfolio page will have some of own content and both will include some content from other static pages. You all most likely know the blog part ;)

Static pages

Things you should know: each static page has it’s title, it’s slug or name (the thing that shows up in your browsers address bar: http://example.com/portfolio/ - right there, the portfolio is the slug!), has the parent attribute and the template attribute. The parent attribute is used when it’s needed to make one page a child of another, i.e. to show Page2 as a subpage of Page1. The template attribute is used when we want to apply some different layout and styling to a static page. Read more about static pages and how to create your own page templates.

If you want to, you can download the theme I created for this tutorial from here (it’s not a designers masterpiece, what did you expect?), or you can use any theme you want.

I hope you read the part on creating page templates, I really don’t feel like explaining the next part.

Create 3 new files in your template directory (if you’re using my theme, these files are already there): home.php, portfolio.php and blog.php. Contents of these files are:

// home.php
<?php
/*
Template Name: Home
*/
?>

// portfolio.php
<?php
/*
Template Name: Portfolio
*/
?>

// blog.php
<?php
/*
Template Name: Blog
*/

// Which page of the blog are we on?
$paged = get_query_var('paged');
query_posts('cat=-0&paged='.$paged);

// make posts print only the first part with a link to rest of the post.
global $more;
$more = 0;

//load index to show blog
load_template(TEMPLATEPATH . '/index.php');
?>

To understand the contents of the blog.php file, please take a look at this.

Now, go to the dashboard, the Pages section and write 3 new static pages:

  • Home, with the slug home, for the template choose Home from the drop-down list (it's on the right side) and the parent leave as is (Main Page)
  • Portfolio, with the slug portfolio, for the template choose Portfolio
  • Blog, with the slug blog, for the template choose Blog

You can add some content to the Home and Portfolio pages, but don’t add any to the Blog page.

Organizing links

Now, let’s make that when we are on http://example.com/ it shows us the Home page, instead of the Blog, and when on the http://example.com/blog/ to show us the blog!

Go to Settings->Reading and where it says “First page displays” choose “A static page”, and under the “Front page” drop-down choose “Home”.

Now, go to Settings->Permalinks and change the “Custom structure” to /blog/%postname%/ or whatever is your preferred permalinks structure, but it must start with /blog/! If Wordpress can’t write to your .htaccess file (I hope it can’t!), open it up in your editor and type the following (or similar, depends on your setup):

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /blog/
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>

The point is in the RewriteBase, with that we’re telling WP where to find the blog. On default setups, when http://example.com/ points to the blog, the RewriteBase is simply / but with the blog located at http://example.com/blog/ we need to change the RewriteBase. If all is well, we’re done with organizing the links.

While you’re still in the dashboard, write some new static pages with content. For the parent of these pages choose Portfolio and leave the template the default (the default page template is page.php).

Time for coding!

Here are two functions I wrote for retrieving content from static pages which will be then included in other static pages:

// functions.php
<?php

/**
* Gets last $number_of_subpages from their $parent_page
* If the <!--more--> tag is ignored ($ignore_more=true) returns the entire content of the subpages
*
* @param mixed $parent_page Contains either the slug of the parent page or it's ID
* @param integer $number_of_subpages Number of subpages to return
* @param boolean $ignore_more Whether to ignore the <!--more--> tag or not
* @return array Contents and titles of subapages
*/
function wpascms_get_subpages($parent_page='portfolio', $number_of_subpages=2, $ignore_more=false)
{
    global $wpdb;

    if(is_string($parent_page))
    {
        $parent_page_ID = wpascms_get_parent_page_ID($parent_page);
    }
    else
    {
        $parent_page_ID = $parent_page;
    }  

    if($number_of_subpages == 0)
    {
        $limit = '';
    }
    else
    {
        $limit = 'LIMIT 0, ' . $number_of_subpages;
    }
    // Get all subpages that are published and are childs of the given parent page
    // and order them by date in descending order (latest first)
    // also, if needed, limit to the latest $number_of_subpages
    $subpages = $wpdb->get_results("SELECT * FROM $wpdb->posts
                                    WHERE `post_parent` = '$parent_page_ID' AND `post_type` = 'page' AND `post_status` = 'publish'
                                    ORDER BY `post_date` DESC $limit");

    if(!$ignore_more)
    {
        foreach($subpages as $key=>$subpage)
            if(strpos($subpage->post_content, '<!--more-->') !== false)
            {
                $short_content = explode('<!--more-->', $subpage->post_content, 2);
                $subpages[$key]->post_content = $short_content[0] . '<a href="' . get_permalink($subpage->ID) . '">Read more...</a>';
            }
        }
    }

    return $subpages;
}

function wpascms_get_parent_page_ID($parent_page)
{
    global $wpdb;

    $id = $wpdb->get_var($wpdb->prepare("SELECT ID FROM $wpdb->posts WHERE `post_name` = %s AND `post_type` = 'page' AND `post_status` = 'publish'", $parent_page));

    return $id;
}

?>

The first function, wpascms_get_subpages() returns the given number of subpages from a specific parent page. By default it will break the content on the tag and append a “Read more…” link. The first parameter can be either a string containing the slug of the parent page, or the ID of the parent page. The second parameter is the number of subpages we want returned. If it’s zero, all subpages will be returned. The second function is merely a helper function, to get the id of the parent page based on it’s slug. To read more on querying the database, read this page.

Here’s how I’m calling this function on my example Home page:

<?php
/*
Template name: Home
*/

get_header();
?>

    <div id="home">
    <?php if (have_posts()) : while (have_posts()) : the_post(); ?>

        <h2><?php the_title(); ?></h2>

        <?php the_content('<p class="serif">Read the rest of this page &raquo;</p>'); ?>

    <?php endwhile; endif; ?>
    </div><!-- home -->

    <div id="latest_works">
    <h1>Recent work</h1>
    <?php $subpages = wpascms_get_subpages();
    if(count($subpages) > 0):
        foreach($subpages as $row=>$subpage):
        if($row%2 == 0)
        {
            $class = "left_work";
        }
        else
        {
            $class = "right_work";
        }
    ?>
        <div class="<?php echo $class; ?>">
            <h2><a href=<?php echo get_permalink($subpage->ID); ?>><?php echo $subpage->post_title; ?></a></h2>
                <?php echo $subpage->post_content; ?>
        </div>
    <?php
        endforeach;
    endif;
    ?>
    </div><!-- latest_works -->

<?php
get_footer();
?>

In words: including the header, then showing any content of the home page. After that getting the subpages: by default, wpascms_get_subpages() is getting the newest 2 subpages of the portfolio page. I’m showing the content of the subpages in 2 columns. What we got with this? Add a new subpage to the portfolio and it will automagically show up on the left side column. In the end, including the footer.

Here’s another example from the portfolio page:

<?php
/*
Template name: Portfolio
*/

get_header();
?>

    <div id="portfolio">
    <?php if (have_posts()) : while (have_posts()) : the_post(); ?>

        <h2><?php the_title(); ?></h2>

        <?php the_content('<p class="serif">Read the rest of this page &raquo;</p>'); ?>

    <?php endwhile; endif; ?>
    </div><!-- home -->

    <div id="latest_works">

    <?php $subpages = wpascms_get_subpages('portfolio', 0);
    if(count($subpages) > 0):
        foreach($subpages as $row=>$subpage):
    ?>
        <div class="work">
            <h2><a href=<?php echo get_permalink($subpage->ID); ?>><?php echo $subpage->post_title; ?></a></h2>
                <?php echo $subpage->post_content; ?>
        </div>
    <?php
        endforeach;
    endif;
    ?>
    </div><!-- latest_works -->

<?php
get_footer();
?>

Same thing is happening here: including the header, showing the content of the portfolio page. Getting the subpages, but now all of the subpages that are childs of the portfolio page, and showing them one under the other.

All subpages can be viewed each on it’s own page, but that is just a plain ol’ page.php file, so I’ll skip that.

Don’t limit yourself to the existing plugins or waiting for one tutorial/example that will show how you can make everything. Don’t be afraid to get your hands dirty by hacking some code. It really doesn’t take too much to create magic with Wordpress ;)

Cheers!

Robert Basic

Robert Basic

Software developer making web applications better.

Let's work together!

I would like to help you make your web application better.

Robert Basic © 2008 — 2020
Get the feed