Spoon - A PHP5 Library

The website used to use the highlight_string function from PHP. That works in most cases, but the color coding choices are very limited and need to be set using ini settings (or ini_set for that matter).

I came across highlight.js and so far it seems pretty reliable. They support quite a few programming languages and colors with their script. And the best part is that the compressed file you download will only contain those languages you want to highlight, which keeps the script fast.

Thanks to the new highlighting I managed to apply another color scheme (thx to Dave Lens for his phpzen theme). Check out the example below.

// This is a single-line comment
$stringvariable = "examplestring";
$intvariable = 300;

/**
 * The description of my test class
 *
 * @author Davy Hellemans <davy@spoon-library.com>
 */
class Testclass
{
	public function test($param = 'default')
	{
		return true;
	}
}

The last year I've been seeing a lot of php libraries and frameworks going towards standalone components. The first that comes to mind is Symfony. How great is it that you can pick a single component you like and use that in your project without being forced to use the entire framework/library. It's pretty awesome, let me tell you that!

With Spoon Library I'm choosing to take the same route. What does that mean? Well, I've started creating separate git repo's (on github) that only have one package/component. There are no dependencies forced from within the library. If you do need some functionality between packages, there will be a plugin system. Of course you will still be able to download the entire library at once.

Let me give you an example:
The template engine is being tweaked and all hardcoded dependencies for SpoonForm are removed. Instead there will be a 'form plugin' that you can use if you wish to use forms within the template package. Each plugin will list which version of a component is required to be able to use it. That means you will be able to upgrade specific components without having to worry about other functionality. Say you upgrade the template engine to the latest version, then you will be notified if other plugins you are trying to use will cause any known problems.

Only the most basic packages have been somewhat converted to the PHP 5.3 components. You can check them out on github.

The first form tutorial is now available. The code should mostly speak for itself, but if that's not the case, dare to ask!

Finally the new website has been released. This is mostly a redesign of the previous one, with a few extra features. It's now possible to post comments on tutorials, blogposts and class methods.

I want to thank @yoniweb (Yoni De Beule) for his design skills. He made sure the logo and website look amazing. More thanks go out to @tijsverkoyen for his HTML5 slice work which kicks some serious ass.

Feedback about the redesign/features is always welcome.

We're proud to announce the v1.3.0 release.

Changelog

• Template options may now start with an integer e.g. {option:404}
• The WHERE clause in SpoonDatabase::update and SpoonDatabase::delete may now be null instead of an empty string.
• Added option for headers.sortingIcon in datagrid.tpl - empty <img> elements are no longer shown for default sorting settings.
• Fixed the sorting problem when setting the sortParameter option in a datagrid.
• Bugfix: some classes were using non-existing exceptions, fixed this issue.
• Rewrote a few methods in SpoonFilter for consistency and performance reasons.
• Bugfix: when providing a template to SpoonTemplate::display a few extra checks are performed.
• Bugfix: multiple forms on the same page would produce ambiguous id's resulting in 'invalid' markup.
• Feature: a callback mechanism for exceptions has been added. New constant 'SPOON_EXCEPTION_CALLBACK'.
• Feature: you can now overwrite the token error message in SpoonForm.
• Bugfix: add FOLLOW_LOCATION to SpoonFile::download cURL call so rewrites pose no problem.
• Bugfix: fixed SpoonFilter::isFloat and SpoonFilter::isInteger to work on every float and int instead of relying on regexes.
• Rewrote some small snippets of code to improve performance.
• Bugfix: rewrote SpoonFilter::isInternalReferrer to use PHP's internal parse_url function.
• Bugfix: createThumbnail had been missing from SpoonFormImage.
• Bugfix: form tokens are now working when you have more than one form on your page.
• Feature: SpoonFilter::arrayMapRecursive() now has an optional third parameter $allowedKeys, which allows you to map callback to specified array keys only.
• Bugfix: Custom keys didn't work correctly for SpoonDatagridSourceArray, they do now.
• htmlspecialchars now uses ENT_NOQUOTES by default instead of ENT_QUOTES
• Bugfix: SpoonDatagrid::getColumn no longer triggers an exception when the datagrid contains no results.
• Bugfix: SpoonDropdown::isFilled will no longer equal true when allowExternalData is disabled and the value is not found in the initial list of values. (thx to Dieter Vanden Eynde)
• SpoonFilter::isURL will now acccept domains such as 'spoon.local'
• Feature: added SpoonDirectory::isWritable, a better alternative to the native is_writable function (that can not handle Windows' permissions properly)
• bugfix: fixed SpoonTemplate on Windows for file includes: absolute paths were identified as relative paths
• Feature: added optional parameter to exclude certain columns in all relevant functions of SpoonFileCSV
• Bugfix: SpoonFilter::isURL allows ip(v4 & v6) as URLS from now on
• Feature: when passing null as defaultvalue and type to SpoonFilter::getValue() the return will be null instead of an empty string
• Feature: you no longer need to pass an array with values to a dropdown. A default element will be generated with no value.
• Bugfix: SpoonEmail now uses the charset when building the emails' headers.
• Bugfix: template cycle tags now work as intended. (thx to Matthis Mullie)
• Bugfix: fixed check that used to always fail. Needs to be improved though. (thx to Dieter Vanden Eynde)
• SpoonDatabase now prefixes fields with their tablename (insert/update)
• Exceptions now show the user-agent, if we can find it in the $_SERVER array
• Spoondatabase can now be used with custom ports
• SpoonTemplate does allow empty strings in the cycle-tag from now on.
• SpoonLocale::getCountry added, which allows you to fetch a country in a specific language.
• SpoonLocale: getMonth and getWeekDay added as well.
• SpoonFile::delete now allows you to delete an array of files.
• Rearranged the general authors/owners.
• Bugfix: you can now use named parameters within update queries.
• Bugfix: multiple dropdownfields weren't parsed because of the [].
• Feature: SpoonLocale now contains the supported language names.
• Template-syntax changed for include, iterations & variables
• Unassigned variables don't trigger a notice but gracefully degrade to the template-syntax when SPOON_DEBUG is enabled
• Unassigned forms don't need template recompilation to work when they are in a later stadium assigned
• Cycle-tags now work correctly when nesting an iteration inside itself
• Variables can now go infinitely deep inside associative arrays
• Nearly every character is now allowed as a parameter for parameter-modifiers

The latest tweaks, bugfixes & updates are found on github.

Spoon can now be found on github.com

After some silence due to preparing the release of Spoon 1.2.0, we are back with a few new tutorials. First up is part 1 of the SpoonDatagrid tutorials. The latest version of Spoon brought some improvements (and fixes) to this package, so take into consideration that this tutorial is intended for the 1.2.0 release.

Part 2 will focus more on how you can manipulate the data in your datagrid by using callback functions. Happy coding!

I'm working on an extensive tutorial about SpoonForm, but since I've been getting a lot of questions about forms, here's a brief example to get you started.

SpoonForm example

We're proud to announce the v1.2.0 release.

Changelog

• The directory structure has changed for some packages.
• A few classes have been renamed based on the above changes. People new to Spoon should have an easier time, trying to find the location of the subpackages.
• Spoon::setObjectReference now also returns the instance you provide it.
• When an exception is thrown, we try to add the last PHP error message if it's available.
• SpoonFilter::isURL now allowes square brackets and semicolons.
• SpoonFilter::replaceURLsWithAnchors now allowes square brackets and semicolons.
• If an exception has a code, this code will be used to link to the documentation section on the website which might contain more information about this specific exception.
• Template cycle tags may now contain a few more characters to give more flexibility in your templates.
• Fixed a bug in SpoonTemplate which prevented first/last options to function normally when your arrays did not start with the 0 key element.
• An extension check has been added to make sure 'mbstring' is loaded before you can use any Spoon class.
• Fixed some comments in multiple files.
• Exception-mails are formatted with inline styles.
• Fixed a performance issue with SpoonFormDropdown in the parse method. (thx to Dieter Vanden Eynde)
• Implemented an autoloader for Spoon.
• SpoonFile::download() now deletes empty file handles when the HTTP return status is not 200.
• Added SpoonDatagrid::getTemplate to retrieve the actual template object being used for parsing your datagrid.
• Added initial version of the new SpoonFileCSV class.
• SpoonFilter::toCamelCase now allowes the separator to be a string OR array.
• Fixed a few issues with invalid markup generated by SpoonForm::getTemplateExample() for radiobuttons/checkboxes.
• SpoonFilter now uses ctype & filter_var functions to speed up some checks methods.
• Fixed an issue with the SpoonDatagrid paging template file.
• An extra method 'createThumbnail' has been added to SpoonFormImage.
• Tokens have been implemented in SpoonForm. They are disabled by default.
• Fixed an issue in SpoonFilter::toCamelCase concerning words with uppercase characters in it. eg SpOoN LiBrarY.
• SpoonFilter::getValue() now accepts arrays for the first argument, as well as 'array' for the returnType argument.
• Added SpoonFilter::arrayMapRecursive(), a way to map multi-dimensional arrays with one or more functions.

We're planning to release v1.2.0 on May 12th. At this moment the website is being reworked, using v1.2 of spoon.

Stay tuned!

Our next tutorial in line continues the SpoonDatabase tutorial of last week. Part 2 handles insert/update/delete functionality and the execute() function.

I've been getting reports from people, unable to get Spoon Library up and running. This is because mbstring is a required extension, but no extension check has been implemented yet. In the next release we'll add a series of checks that gives warnings about the extensions that you should enable to use Spoon.

Part 1 of our introduction on how to handle your database traffic in Spoon is now available here. We will show you how to make a connection and fetch single or multiple records in your array format of choice.

Next week's tutorial will cover insert/update/delete functionality and the execute() function. Enjoy!

We're proud to announce our third template tutorial. It explains all there is to know about variable modifiers.

The second tutorial about the template engine has arrived. It contains more information about iterations & cycle tags. This tutoral requires the latest version 1.1.5 of the library.

We're proud to announce the v1.1.5 release.

Changelog

• Added SpoonDate::getTimeAgo which presents you with a language dependant sentence based on the provided timestamp in the past.
• Added SpoonTimeField::getTimestamp which returns a timestamp based on the provided values in conjunction with the hh:ii format in the timefield.
• Fixed a bug in SpoonDateField::getTimestamp when not providing all the optional arguments.
• Template modifiers may now contain colons if you encapsulate with single quotes. eg {$now|date:'Y-m-d H:i'}
• Modifiers are no longer allowed within cache/include tags.
• Implemented a few basic checks in SpoonTemplate for variables, iterations and options.

Our next tutorial in line handles the correct use of SpoonEmail. It illustrates the update it got in 1.1.4 by connecting to Gmail's SMTP server in order to send an e-mail.

We're proud to announce the v1.1.4 release.

Changelog

• Added SpoonTemplate::getContent which returns the output of the executed template. Can not be used in combination with cache tags.
• Added SpoonFilter::stripHTML, it strips all HTML elements from a string. Optional attributes include:
  • Replacing images with alt text
  • Replacing anchor links with their href value
  • Let paragraph elements receive an extra linebreak at the end to keep basic formatting
• SpoonEmail now uses SpoonFilter::stripHTML to generate plain-text contents.
• SpoonEmail now supports SSL and TLS in SMTP connections. Use SpoonEmail::setSMTPSecurity() to set the SMTP security layer.
• When you create a datagrid, the column names will be used as the class attribute.
• SpoonSession::exists now works as intended, pretty similar to SpoonCookie::exists.
• Removed getLanguages from SpoonLocale since the source files were not reliable.
• You can now use SpoonDropDown::setOptionAttributes to add some custom attributes to specific options in a dropdown. Examples are 'disabled' or 'rel'.
• Added htmlspecialcharsDecode to SpoonFilter.
• Reworked SpoonSession::delete to offer the same flexibility as SpoonCookie::delete.
• Added SpoonDataGrid::getColumn which grants you access to the actual SpoonDataGridColumn object, providing you with more options to set for a column.
• Internal code has been refactored to implement the new naming conventions for arrays.

A basic tutorial has been added for the SpoonSession class. It will describe the general behaviour of SpoonSession, as well as provide a small insight on the HTTP session mechanics

We're proud to announce the tutorials section.

Currently only 3 tutorials have been released, but more will follow. We aim at an average of 1 tutorial each week. At first we focus on the basic tutorials concerning most used components such as Spoon, SpoonTemplate, SpoonForm and so on. New tutorials will be announced here.

Next up is the second part about the template engine.

We're proud to announce the v1.1.3 bugfix release.

Changelog

• Added SpoonImageField, it extends SpoonFileField with some image-specific methods:
  • getExtension(): returns the extension based on the IMAGETYPE
  • hasMinimumDimensions(): checks if the image has minimum width and height
  • isValidMimeType(): a filter based on given MIME-types
• Added Dave to the main-authors (Welcome Dave!)
• Fixed some PHP-doc
• Fixed a bug in SpoonTemplateModifiers::createHTMLLinks(), it should handle urls correct from now on
• Added an extra element in the return of SpoonFile::getInfo(). The element is called human_readable_size and contains the size of the file in a human readable way.
• $_FILES is now included in the variables-section of Exceptions.
• Added SpoonTemplate::getAssignedValue to fetch already assigned values.
• Fixed an issue with required files not being included.
• Rewrote the way SpoonCheckBox & SpoonRadioButton work. The number of required parameters & options has been increased.
• SpoonCookie::unset now works as intended (thx to Dieter Vanden Eynde)
• Fixed an issue when using multiple cycle tags on one page
• Based on SPOON_DEBUG the error_reporting for a compiled template is set to E_WARNING or E_ALL | E_STRICT

We're proud to announce the v1.1.1 bugfix release.

Changelog

• SpoonThumbnail: changed the name of checkFileType to isSupportedFileType
• There are no final classes anymore, everthing should be extendable
• Filesystem: created an alias for SpoonDirectory::move in SpoonFile
• Filesystem: SpoonDirectory move hasn't a strict-argument anymore and will trigger exceptions on failure. If the destinationpath doesn't exist it will be created
• Added a new Package: SpoonRESTClient, be carefull it is not backwards compatible with the version pre 1.1.x
• SpoonTemplateModifiers::truncate(HTML) were removed for now, they need to be reworked.

We're proud to announce the release of v1.1.0.

Changelog

• An additional constant 'SPOON_CHARSET' has been added. This will be used by default.
• SpoonCookie & SpoonSession no longer use the 'strict' setting. They will return false on failure.
• SpoonHTTP::isSent no longer throws an Exception.
• SpoonDatabase is now using PHP's PDO which results in a speed increase.
• Added a method in SpoonFile to download a file (SpoonFile::download)
• Fixed a typo in SpoonDirectory::getSize
• Bugfix: SpoonDirectory::getList won't return files listed in the exclude-array anymore
• Bugfix: SpoonDirectory::delete doesn't use SpoonFile::getList anymore because this function doesn't exists
• Bugfix: SpoonDirectory::getSize doesn't use SpoonFile::getList anymore because this function doesn't exists
• SpoonLocale was added. This package contains some nifty lists in multiple languages (countries, days of the week, ...)
• SpoonDate has now only 1 method related to dates. The others were moved to SpoonLocale.
• SpoonRadioButton, SpoonMultiCheckBox & SpoonDropDown now have an extra option that allows the default security measurements to be overruled.
• SpoonDataGrid now seems to be in check with the changes made to the other parts of the library.
• SpoonFilter::isURL now allows tildes.
• Some classes are now united into one file for speed.

It might seem as if we've been slacking, but behind the spoon scenery we're getting ready to release v1.1.0

About a month ago, I attended a presentation about utf8 support in PHP and decided to make some tweaks to Spoon so that it runs smoothly with utf8. Therefor the release of v1.1.0 was pushed back quite a bit. In the meanwhile we're working on the documentation and tutorials. Mark July 1st on your calendar!

Quite a few ideas for the v1.1.x release are popping up. Here are a few of my own. Feel free to leave your suggestions in the comments

• SpoonDatabase will be using PDO
• Localisation files will be created for the most common terms & a specific module could/will be devoted to it.
• SpoonForm and its elements will be revised, since I still think that creating large forms is too much of a hassle.
• The template engine is going to be reworked internally, because I want to be able to add project specific functionality (within certain limits).

On a sidenote, we're currently revising the layout, after which the first decent tutorials will be released.

We're proud to announce the release of v1.0.3.

Changelog

• Template engine now parses forms with their variable options to the compiled version (thx to Pieter Meyvaert)
• SpoonDatabase: using tables instead of table as variable name
• SpoonDatabase: if the handler doesn't exists it should be created when calling getHandler
• SpoonImage: removed unused code
• SpoonDataGrid now has a method to retrieve the number of results (getNumResults)
• You can now set your compile directory for datagrid templates
• SpoonDataGrid::setAttributes now works as intended
• Added a number of methods to be able to clear attributes within datagrids.
• SpoonFilter::isURL allowes @ from now on
• SpoonRSS::isValid to check for valid feed
• SpoonRSS::readFromFeed will ignore invalid data
• SpoonDate updated the values of the keys when asking for days/months of the year.
• SpoonDatabase fixed minor issue where an exception could not be shown properly with parameter issues
• Updated package info for SpoonThumbnail
• Fixed an issue with SpoonForm and the default enctype.
• Datagrid now has the correct colspan value made available in the template
• When using maxlength this will be used when retrieving the value with getValue()

We're proud to announce the release of v1.0.2 of our beloved library.

Changelog

• Exceptions now include the hostname, if available
• Session variables via SpoonSession are no longer converted to a string
• Template includes now work as initially intended (thx to Pieter Meyvaert)
• Inverse template options using the ! sign are now available
• Template engine now has 2 default variables (TAB & CRLF)
• The form package has been tested with E_STRICT
• SpoonEmail now accepts templates and their needed variables through 2 new methods (setHTMLContent and setPlainContent)
• Removed method setContent in SpoonEmail
• SpoonEmail now strips HTML tags from the HTML body when no plain template is chosen
• Fixed bug in SpoonEmail where returning output would sometimes trigger an error
• Made SpoonFilter::isEmail somewhat compatible with RFC 5322 (not fully implemented yet)
• SpoonFilter::isURL supports ip-addresses. (thx to Pieter Claerhout)
• SpoonSession has an extra method: SpoonSession::delete($key)
• SpoonCookie has an extra method: SpoonCookie::delete($key)
• SpoonCookie::set fixed a bug, with serializing data

Since the tutorials section is not yet implemented I've added two basic tutorials for the template engine & forms on the main page of the documentation.

We are proud to announce the 1.0.1 release of our beloved library. Most of the changes are minor bugfixes.

Changelog

• Renamed SpoonDatabase::getNumberOfExecutedQueries to getNumQueries.
• Fixed problem with SpoonDatabase::getNumRows
• Reworked the datagrid templates, based on the changes in SpoonTemplateCompiler
• SpoonRSS now requires SpoonRSSItem

We are proud to announce the 1.0.0 release of our beloved PHP5 library.

There's no list available of all the changes, since there are just too many. Consult the documentation & tutorials on the website to find out what's new