====== Request for Comments: Namespaces for internal classes ======
  * Version: 0.1
  * Date: 2008-03-06
  * Author: Lars Strojny <lstrojny@php.net>
  * Status: Work in progress
  * First Published at: none

===== Introduction =====

This RFC discusses the transition to real namespaces for internal classes in e.g. ext/spl.

==== Why should we use namespaces for internal classes? ====

Currently internal classes are inconsistently named. Just take a look at SPL:
  * RecursiveIterator
  * RecursiveIteratorIterator
  * RecursiveRegexIterator
  * RegexIterator
  * RuntimeException
  * SeekableIterator
  * SimpleXMLIterator
  * SplFileInfo
  * SplFileObject
  * SplObjectStorage
  * SplObserver

Some of the classes in ext/spl are prefixed with "Spl", some are not. To avoid naming collisions and as a structural element, namespaces were introduced in PHP 5.3. This gives us a chance to move all the Spl-classes in appropriate namespaces. Take a look at the following transitions:

  * RecursiveIterator: Spl::Iterator::Recursive
  * RecursiveIteratorIterator: Spl::Iterator::Recursive::Iterator
  * RecursiveRegexIterator: Spl::Iterator::Recursive::RegexIterator
  * RegexIterator: Spl::Iterator::Regex
  * RuntimeException: Spl::Exception::Runtime
  * SimpleXMLIterator: Spl::Iterator::SimpleXML
  * SplObserver: Spl::Observer::Observer
  * SplSubject: Spl::Observer::Subject
  * SplFileInfo: Spl::File::Info
  * SplFileObject: Spl::File::Object
  * SeekableIterator: Spl::Iterator::Seekable

===== List of renamed classes =====
==== Array ====
^ Current name                    ^ New name ^
| ArrayObject                     | Spl::Array::Object |
| SplFastArray                    | Spl::Array::Fast |

==== Iterators ====
^ Current name                    ^ New name ^
| AppendIterator                  | Spl::Iterator::Append |
| ArrayIterator                   | Spl::Iterator::Array |
| CachingIterator                 | Spl::Iterator::Caching |
| DirectoryIterator               | Spl::Iterator::Directory |
| EmptyIterator                   | Spl::Iterator::Empty |
| FilesystemIterator              | Spl::Iterator::Filesystem |
| FilterIterator                  | Spl::Iterator::Filter |
| GlobIterator                    | Spl::Iterator::Glob |
| InfiniteIterator                | Spl::Iterator::Infinite |
| IteratorIterator                | Spl::Iterator::Iterator |
| LimitIterator                   | Spl::Iterator::Limit |
| RegexIterator                   | Spl::Iterator::Regex |
| SeekableIterator                | Spl::Iterator::Seekable |
| SimpleXMLIterator               | Spl::Iterator::SimpleXML |
| ParentIterator                  | Spl::iterator::Parent |
| NoRewindIterator                | Spl::Iterator::NoRewind |
| OuterIterator                   | Spl::Iterator::Outer |
| RecursiveArrayIterator          | Spl::Iterator::Recursive::Array |
| RecursiveCachingIterator        | Spl::iterator::Recursive::Caching |
| RecursiveDirectoryIterator      | Spl::Iterator::Recursive::Directory |
| RecursiveFilterIterator         | Spl::Iterator::Recursive::Filter |
| RecursiveIterator               | Spl::Iterator::Recursive::Recursive |
| RecursiveIteratorIterator       | Spl::Iterator::Recursive::Iterator |
| RecursiveRegexIterator          | Spl::Iterator::Recursive::Regex |

==== Lists ====
^ Current name                    ^ New name ^
| SplDoublyLinkedList             | Spl::List::DoublyLinked |
| SplQueue                        | Spl::List::Queue |
| SplStack                        | Spl::List::Stack |
| SplHeap                         | Spl::List::Heap |
| SplMinHeap                      | Spl::List::MinHeap |
| SplMaxHeap                      | Spl::List::MaxHeap |
| SplPriorityQueue                | Spl::List::PriorityQueue |
| SplObjectStorage                | Spl::List::ObjectStorage |

==== Exceptions ====
^ Current name                    ^ New name ^
| BadFunctionCallException        | Spl::Exception::BadFunctionCall |
| BadMethodCallException          | Spl::Exception::BadMethodCall |
| DomainException                 | Spl::Exception::Domain |
| InvalidArgumentException        | Spl::Exception::InvalidArgument |
| LengthException                 | Spl::Exception::Length |
| RangeException                  | Spl::Exception::Range |
| RuntimeException                | Spl::Exception::Runtime |
| LogicException                  | Spl::Exception::Logic |
| OutOfBoundsException            | Spl::Exception::OutOfBounds |
| OutOfRangeException             | Spl::Exception::OutOfRange |
| OverflowException               | Spl::Exception::Overflow |
| UnderflowException              | Spl::Exception::UnderflowException |
| UnexpectedValueException        | Spl::Exception::UnexpectedValue |

==== File related stuff ====
^ Current name                    ^ New name ^
| SplFileInfo                     | Spl::File::Info |
| SplFileObject                   | Spl::File::Object |
| SplTempFileObject               | Spl::File::TempFile |

==== Observer interfaces ====
^ Current name                    ^ New name ^
| SplObserver                     | Spl::Observer::Observer |
| SplSubject                      | Spl::Observer::Subject |

==== Misc ====
^ Current name                    ^ New name ^
| Countable                       | Spl::Countable |

===== Backwards compatibility and other constraints ======
  * The current names are removed in PHP 6.0
  * The current names are available as deprecated aliases until their removal
  * The documentation will be updated to advise the usage of the new naming scheme
  * The current classes will trigger an E_DEPRECATED warning hinting the new name