Miles Johnson

Titon

For the past few years I've been working on a project called Titon — a PHP framework and a front-end library built on MooTools. Titon refers to anything back-end related as the "Framework", while anything front-end related as the "Toolkit". The Framework isn't full-stack in the modern sense, it's simply a collection of packages that can be installed through Composer. The Toolkit is a collection of modular UI classes and helpers written in HTML5, CSS3, Sass and MooTools 1.4.

A brief history

I started writing Titon back in September 2009, around the same time PHP 5.3 was released. The idea behind Titon was simply a learning lesson. It gave me a chance to learn namespaces, closures and all the new PHP functionality. It also permitted me to write systems I would never really write, like database abstraction layers, object relational mappers, caching and storage engines, internationalization and localization, routing, so on and so forth. It was also a great learning lesson on how to properly use interfaces and abstraction classes, while also practicing design patterns and improving with design principles like DRY, KISS, YAGNI, and many others.

Over the course of 3 years, the Titon codebase evolved into a fully fledged framework (albeit not 100% runnable). The architecture was rewritten about 3-4 times as I would try new, different and unique approaches. Classes and interfaces came and went. Functionality was stripped (YAGNI) or dumbed down (KISS). Features were completed or backlogged. Roadmaps were created and abruptly forgotten about. Writing a full-stack framework took time and eventually I stopped working on it many months at a time.

It was around 2012 when I jumped back onto Titon. With the recent release of PHP 5.4 and the ever increasing usage of Composer, it felt like the perfect time. Instead of building a full-stack framework (because do we really need another framework) like before, I decided to break it down into multiple smaller packages that can be installed through the Composer. This would encourage usability, promote decoupling and not require a developer to use a heavy framework for certain functionality. Over the course of the next year, I broke it down into 15 primary packages and 4 supporting packages.

Why am I releasing it?

Even though it was a learning lesson, these packages could still be beneficial to someone (or even you), hence the release. I don't expect Titon to compete with Symfony, CakePHP, Zend, or the many other frameworks, nor do I care. If a packages solves a problem you have, then perfect, go ahead and use it! If a package or Titon as a whole is never used, I won't mind either way. In the end, it taught me everything I currently know, and I couldn't be happier.

What are the Framework packages?

Like previously mentioned, Titon is decoupled into 15 primary packages and 4 supporting packages. A primary package is a collection of classes that provide functionality for a specific feature, for example, a model layer, route mapper, or caching engine. A supporting package is an optional dependency for primary packages that include additional functionality, for example, the MySQL driver for the Model package.

The following packages are available, fully functional and tested. They are split between PHP 5.3 and 5.4, as there was no reason to limit simplistic packages to 5.4 only.

PHP 5.3

• Debug - Provides logging, debugging and advanced error and exception handling
• Environment - Allows for multiple environment configuration and bootstrapping
• Event - Notifies a list of objects during an event and allows for listener registration
• Type - Implements class like functionality for arrays, strings, objects and enums
• Utility - Provides convenience classes for basic tasks like validation, formatting, sanitization and more

PHP 5.4

• Cache - Provides a data caching layer that supports multiple storage engines
• Common - Provides global functionality like class traits and augmentation as well as dependency and configuration management
• Controller - Provides controllers that handle the HTTP dispatch cycle and are loosely coupled with other packages
• G11n - Implements localization and internationalization through message and locale bundles
• HTTP - Provides classes for interacting with sessions, cookies and the request and response
• IO - Permits file system manipulation through readers, writers and resource bundles
• Model - Implements a lightweight database abstraction layer and an object relational mapper
  • MySQL - Enables the MySQL database driver
  • PostgreSQL - Enables the PostgreSQL database driver
  • SQLite - Enables the SQLite database driver
  • MongoDB - Enables the MongoDB database driver
• MVC - Bundles the Model, View and Controller packages while adding support for dispatching and modularization
• Route - Provides dynamic route handling, matching and mapping
• View - Allows for template look-up and rendering through engines and helpers

What about the Toolkit?

The Toolkit is a collection of JavaScript classes and CSS modules known as components. Each component provides front-end functionality, like modals, tooltips and buttons. But doesn't this compete with Twitter bootstrap? In a sense yes, however, there are some major differences. The first being that Toolkit uses MooTools instead of jQuery (if you're one of the rare developers like me who don't like jQuery). The second being that Toolkit doesn't provide default styles like Bootstrap, it merely provides the functionality. This allows the developer – you – to integrate and customize the components at will.

The following components are currently available. Each component is either purely CSS or a combination of CSS and JavaScript.

JavaScript

• Accordion - Provides collapsible support to a list of sections
• Blackout - Displays a transparent black element over the document
• Cache - Provides local and session storage within the class layer
• Flyout - Displays nested flyout menus that appear below an element that activates it
• LazyLoad - Provides an easy way to lazy-load images (inline and background) while scrolling
• Modal - Displays dynamic modals that will display above the content
• Pin - Pin an element in a container that stays within the viewport while scrolling
• Popover - Displays dynamic notification elements over an element
• Tabs - Provides tabbed support to an element containing navigation tabs and sections
• Timers - Provides timer and interval management within the class layer
• Tooltip - Displays dynamic tooltips over an element or the mouse cursor
• TypeAhead - Displays a list of possible options below an input while typing

CSS

• Animations - CSS3 transitions for specific animations: fade, slide, etc
• Alert - Styles for block level notification messages
• Button - Styles for generic cross-browser compatible buttons
• ButtonGroup - Allows for the grouping of multiple buttons into 1 visual styled button
• Icon - Allows for inline image sprites to be used at 12, 16, 24, 32, and 64 sizes
• Label - Styles for inline tag labels
• Badge - Styles for inline notification bubbles
• Pagination - Styles for pagination lists
• Visual - Provides visual aesthetics like gloss and glare over elements

What about a full application?

Nothing is stopping you from using Titon as a full application — hell, even the MVC package was built for this purpose. Since Titon is a collection of packages, there's no set guidelines on how to build an application, it's all up to how you want to piece it together. However, to make things easier, I've thrown together a skeleton application that you may use as a base.

What does the future hold?

In regards to the Framework, I have no plans to add anymore primary packages. I do have plans to add minor supporting packages, like Smarty and Twig support for the View layer. Any bugs, issues or feature requests I will handle of course. I would also like to increase unit testing and average around 90% code coverage for all packages.

The Toolkit however will receive full support and the inclusion of many more components. I currently use Toolkit on all my personal websites.

In the off chance that Titon becomes popular, I will provide in-depth documentation, a fully functional website, and reverse my decision on new packages.

How can you start using it?

By installing through Composer, or cloning the repository, or downloading the project. Since no official website exists, nor does any documentation, learning how to use each package can be tricky. Each repository contains a docs folder that provides basic documentation on each class in the repo. For any functionality that is not documented, I highly suggested reading the source code and its comments. And if no documentation exists for a specific class, let me know and I will provide one.

Using Toolkit requires some manual intervention as the source files need to be compiled. This allows for custom Toolkit builds (only requiring certain components) to be generated through Grunt. Instructions on how to do this can be found in the repository.

I will also be blogging about each package and how to use it, so expect those in the near future!

Blue Screens and SSDs

Over the past weekend I spent 3 days troubleshooting a constant blue screen of death problem. It was like no problem I've ever dealt with as the symptoms were very unusual. When I was using the computer, whether playing a game, browsing the internet or simply just working, it would freeze up. It wouldn't freeze in the usual sense, it would freeze up program by program (when I clicked to each one) until I couldn't do anything except move my mouse and wait for the unavoidable BSOD. It would even BSOD while my computer was idle, weird!

Like any competent PC owner, I tested all the hardware piece by piece. I started by disassembling the computer, cleaning everything, checking for damage, and reassembling; all good. I checked all drivers and updates. I tested each memory stick one by one. I monitored the temperature and voltage, and found nothing out of the ordinary. That only left the video card, power supply, hard drives (1 SSD, 2 HDD) and possibly the motherboard. I ruled out the power supply by monitoring the voltage. I ran disk cleanup, disk check and defragment on all the drives and they all passed. I never tested another video card as I believed it wasn't a video issue, since the symptoms had nothing to do with display. That left me with the MOBO, which I was really hoping wasn't the problem.

Before I went any further, I queried all my tech knowledgeable friends for a solution... they had none. They all suggested doing a system wipe, which I think is absurd until you determine whether it's a hardware or software issue. So I enabled BSOD logging which would allow me to read the dumps and discover a solution. However, another problem arose when the BSOD dumps were never written during a crash, and the administrative event logs weren't helpful either. I was at a loss at this point and really didn't want to spend money building a new system.

Since BSOD logs weren't being generated, a friend suggested waiting for a BSOD to occur and to write down the error message that appears. So I did. The following is a summary of the BSOD.

A process or thread crucial to system operation has unexpectedly exited or been terminated. Stop: 0x000000F4 (0x0000000000000003, 0xFFFFFA800C13D060, 0xFFFFFA800C13D340, 0XFFFFF800039D9350).

At a glance it doesn't come off as helpful, but that didn't stop me. I Googled around using "BSOD 0x000000F4" as my term coupled with each piece of hardware I was utilizing, until I found something. It just so happens that my Crucial M4 SSD that I installed a little over a year ago was the culprit. After 5,000 hours of on-time, the SSD will crash unexpectedly. The math since installation checks out: (12 average hours a day * 30 days a month) * 14 months = 5,040. With a little firmware update from the Crucial guys, I've been BSOD free for a couple days now.

I felt the need to blog this as I'm sure it would be helpful to others who encounter such weird issues, especially with new tech like SSDs. You've been warned!

Changelogs: Decoda v6.2.0

A new version of Decoda has been released, version 6.2.0. Please download the new tag or view the documentation. If you have any questions, be sure to send me an email or comment on this post. If you run into any problems, report an issue on the GitHub repository.

Version: 6.2.0
Tested On: PHP 5.4.3, Composer
Requires: PHP 5.3, Composer
Commit Hash: e90e79fddb88aff3928eb74018594b5717080e1b
Changes:

• Added a newline to line break conversion setting lineBreaks [#48]
• Added an onlyTags setting to filters that only allow tags and no text nodes as direct descendants
• Added [*] list item tag to ListFilter (does not support nested lists)
• Changed utility methods to public from protected
• Improved newline normalization

Updating Composer in Travis

If you're using Composer in Travis, it's a good idea to update Composer before each build. If you do not update, you may receive warnings like the following.

Warning: This development build of composer is over 30 days old. It is recommended to update it by running "/home/travis/.phpenv/versions/5.4.13/bin/composer.phar self-update" to get the latest version.

It seems the Travis environment isn't completely reset between builds and jobs. Tests should always be ran using the latest version of Composer, so place a selfupdate in before_script.

before_script:
  - composer selfupdate
  - composer install

Changelogs: Uploader v4.3.0

A new version of Uploader has been released, version 4.3.0. Please download the new tag or view the documentation. If you have any questions, be sure to send me an email or comment on this post. If you run into any problems, report an issue on the GitHub repository.

Version: 4.3.0
Tested On: PHP 5.4.3, CakePHP 2.3.6, Composer
Requires: PHP 5.3, CakePHP 2.3, Composer
Commit Hash: 6bcd77330c5e7a4ce62f60d633b19dfba05e6a50
Changes:

• Includes changes from previous minor versions
• Updated Transit to v1.4.0
• Added transportDir setting for uploads and transforms which allow custom transport directory paths [Issue #125]
• Added fit transformer that allows for fitting an image to a certain size while applying a background fill
• Added 4th argument to AttachmentBehavior.deleteFiles() to circumvent database hit
• Reversed move and rename logic so transformed files do not conflict
• Fixed bug where empty file paths trigger error on deletion [Issue #126]

Prism PHP Support

If you follow me on GitHub you may have noticed that I forked and committed quite a bit to the wonderful Prism JS project by Lea Verou. If you don't know what Prism is, it's a lightweight syntax highlighter written in JavaScript. It's what powers the syntax highlighting for my code blocks.

My major contribution to the project was full PHP highlighting support (including 5.3 and 5.4), as well as some improvements to the C-Like language and the inclusion of the CSS extras language. Take a look at the PHP snippet below which is taken from my Titon\Model project.

/**
 * @copyright	Copyright 2010-2013, The Titon Project
 * @license		http://opensource.org/licenses/bsd-license.php
 * @link		http://titon.io
 */
namespace Titon\Model;
use Titon\Common\Base;
use Titon\Common\Traits\Attachable;
use Titon\Model\Relation;
class Model extends Base {
	use Attachable;
	protected $_config = [
		'connection' => 'default',
		'table' => '',
		'prefix' => '',
		'primaryKey' => 'id',
		'displayField' => ['title', 'name', 'id'],
		'entity' => 'Titon\Model\Entity'
	];
	public function addRelation(Relation $relation) {
		$this->_relations[$relation->getAlias()] = $relation;
		$this->attachObject([
			'alias' => $relation->getAlias(),
			'class' => $relation->getModel(),
			'interface' => 'Titon\Model\Model'
		]);
		return $relation;
	}
	public function createTable(array $options = [], $temporary = false) {
		$schema = $this->getSchema();
		$schema->addOptions($options + [
			Dialect::ENGINE => 'InnoDB',
			Dialect::CHARACTER_SET => $this->getDriver()->getEncoding()
		]);
		return (bool) $this->query(Query::CREATE_TABLE)
			->attribute('temporary', $temporary)
			->schema($schema)
			->save();
	}
	public function getPrimaryKey() {
		return $this->cache(__METHOD__, function() {
			$pk = $this->config->primaryKey;
			$schema = $this->getSchema();
			if ($schema->hasColumn($pk)) {
				return $pk;
			}
			if ($pk = $schema->getPrimaryKey()) {
				return $pk['columns'][0];
			}
			return 'id';
		});
	}
}

The language also supports seamless integration with HTML markup. The snippet below is taken from my Titon\Debug project.

<div class="titon-debug">
	<div class="debug-head">
		<abbr title="<?php echo $file; ?>" class="debug-file">
			<?php echo self::parseFile($file) . ':'; ?><!--
			--><span class="debug-line"><?php echo $line; ?></span>
		</abbr>
	</div>
	<?php foreach ($vars as $var) { ?>
		<div class="debug-output">
			<?php if (isset($dump)) {
				echo self::_renderTemplate('table', array('value' => $var));
			} else { ?>
				<pre><code><?php echo \Titon\esc(print_r($var, true)); ?></code></pre>
			<?php } ?>
		</div>
	<?php } ?>
</div>

I hope you all find use in this contribution! Feel free to report any issues or suggestions to me.