Permalink
Browse files

Added slugifier proposal

  • Loading branch information...
1 parent af6968e commit 579df74806adf3ad4642b0fa9d71b62d2ce8ac7c @dantleech committed Mar 21, 2013
Showing with 79 additions and 0 deletions.
  1. +79 −0 proposed/slugifier.md
View
@@ -0,0 +1,79 @@
+Slugifier Interface
+===================
+
+This document describes a common interface for slugifier libraries.
+
+The goal is to provide a simple common interface for classes which generate
+*slugs*. Such classes are commonly known as *slugifiers* or *urlizers*.
+
+There are many slugifier libraries in existance, each of which handles the
+process in a slightly different way.
+
+Frameworks and CMSs that have custom needs MAY extend the interface for their own
+purpose, but SHOULD remain compatible with this document. This ensures
+that the third-party libraries an application uses can write to the
+centralized application logs.
@lsmith77

lsmith77 Mar 21, 2013

text needs to be updated to not talk about log

+
+The terms `slugify` refers to the process of transforming a string into a URL-safe
@lsmith77

lsmith77 Mar 21, 2013

it might make sense to reference an RFC to define what "URL-safe" means.

@lsmith77

lsmith77 Mar 21, 2013

ah doh .. you linked the RFC further down .. so nevermind :)

+version of itself.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+interpreted as described in [RFC 2119][].
+
+The word `implementor` in this document is to be interpreted as someone
+implementing the `SligifierInterface` in a slugifier-related library or framework.
+Users of slugifiers are refered to as `user`.
+
+[RFC 2119]: http://tools.ietf.org/html/rfc2119
+
+1. Specification
+-----------------
+
+### 1.1 Basics
+
+- The `SlugifierInterface` exposes one method, `slugify`, which accepts any
+ type of *source string* and returns a *slugified* string, the *return string*.
+
+### 1.2 Source string
+
+ - The implementing class method MUST accept source strings of any description.
+
+### 1.3 Return string
+
+ - The return string must be URL-safe and there for MUST NOT contain any characters
+ forbidden in [RFC1738][].
+
+[RFC 1738]: http://tools.ietf.org/html/rfc1738
+
+2. Package
+----------
+
+The interface described and a test suite to verify your implementation is provided
+in [psr/slugifier](https://packagist.org/__________) package.
+
+3. `Psr\Log\SlugifierInterface`
@lsmith77

lsmith77 Mar 21, 2013

subnamespace needs to be updated

+-------------------------------
+
+```php
+<?php
+
+namespace Psr\Log;
@lsmith77

lsmith77 Mar 21, 2013

subnamespace needs to be updated

+
+/**
+ * Describes a slugifier instance
+ *
+ * See _______
+ * for the full interface specification.
+ */
+interface SlugifierInterface
+{
+ /**
+ * Return a URL safe version of a string.
+ *
+ * @param string $string
+ * @return string
+ */
+ public function slugifiy($string);
@lsmith77

lsmith77 Mar 21, 2013

typo in the method name

+}
+```

1 comment on commit 579df74

I guess one expectation related to this is to ensure that the slug is unique. I guess what would happen then is that someone would create a slugifier that is able to f.e. do a DB lookup to check if the slug exits already and if it does, add some integer etc.

then again as soon as this is done, one would also need some identifier (f.e. the parent path) etc, so maybe such things are beyond the scope of this interface.

Please sign in to comment.