primitives's Introduction

Objective PHP / Primitives

Disclaimer

This document is written in globish, the flavour of English we're trying to use in France. We know how bad our english is, please don't pay too much attention to it :)

Although we're thinking to this library for a while now, its implementation is still in early stage, and for the next coming months, you'll probably see a few code and a lot of changes in it. This means that if you're interested in this project, you're more than welcome to try it, contribute to it, make proposals for it, but please don't use it in production projects for now!

Project introduction

Primitives objects are foundation of Objective PHP. Objective PHP aims at providing some high-level component to provide PHP with a more objective syntax. The goals of Objective PHP libraries can be summed up like this:

make extensive use of PHP OOP capabilities
work with data objects, no multipurpose, dummy containers (aka variables)
package commonly needed data processing into reliable, efficient and unit tested methods
turn any error in Exception to ease failure handling
bring to PHP a more elegant, modern and fluent way to write code (partly inspired by Javascript)
auto-completion minded library for enhancing developer productivity
make use of more language's features (like closures)

Our primitives library is intended achieve most of these goals. The very first set of object will contain:

ObjectivePHP\Primitives\String
ObjectivePHP\Primitives\Collection

Each of them will both wrap native functions in a object-oriented way and expose higher level methods to perform many usual data manipulation over those. More on this coming soon, in another document describing the coding standard and rules.

What's next?

First, we'll focus on the three above mentioned classes. We'll consider releasing a 1.0 version once they are ready to get implemented in third-party code with total reliability. Starting from here, we'll be able to work on a much more detailed roadmap.

This roadmap will not only anticipate Primitives library evolutions, but also include parallel development of extended libraries, built on top of Primitives, and offering some even higher level components for real life use:

HTML Tag
CSS Styles
File/Stream
Image
Point (coordinates)
...

These are just some examples of what kind of classes we intend to work on, but much more are to come.

Once again, you all are invited to contribute by submitting us proposals, trying and testing what we do, contribute (code or documentation). For any contact, please drop us a message at [email protected]

Installation

Manual

You can clone our Github repository by running:

git clone http://github.com/objective-php/primitives

If you're to proceed this way, you probably don't need more explanation about how to use the library :)

Composer

The easiest way to install the library and get ready to play with it is by using Composer. Run the following command in an empty folder you just created for Primitives:

composer require --dev objective-php/primitives:dev-master

Then, you can start coding using primitive classes by requiring Composer's autoload.php located in its vendor directory.

Hmm, before starting coding, please take the time to read this file till the end :)

How to test the work in progress?

Run unit tests

First of all, before playing around with our primitives, please always run the unit tests suite. Our tests are written using PHPUnit, and can be run as follow:

cd [clone directory]/tests
./phpunit .

Write some code

At this time, you're on your own to find out what Primitives can do for you, sorry for that, we'll soon work on some samples to help you getting started. Meanwhile, you can instantiate the various classes and learn by yourself their capabilities by relying on your IDE auto-completion feature ;)

use ObjectivePHP\Primitives\String;
use ObjectivePHP\Primitives\Collection;

// allow Primitives classes autoloading
// Note: this is assuming you used Composer to install the library!
require 'vendor/autoload.php';

$identifier = new String(uniqid());
$server = new Collection($_SERVER);

May the OOP be with PHP!

primitives's People

Contributors

Stargazers

Watchers

primitives's Issues

Collection::has() returns false if corresponding value === null

This is because of Collection::offsetGet() using isset() rather than array_key_exists

return isset($this->getInternalValue()[$offset]);

Add a DateTime primitive

There is not many to add to the native DateTime object, but at least adding a static ::cast($string) method would be convenient and consistent with other types.

Clarify API status with methods that modify receiver

For methods that modify the internal state of primitive objects, we must decide if the returned value should be the current reference or a new instance.

In almost all languages where scalars are objects, operations are applied on a new instance, which is returned. We should stick to this behavior, and not consider such methods as kind of implicit mutators.
This is a common accepted (and expected) behavior.

In Ruby:

str = "Hello World";
str.downcase.hash == str.hash # False

Ruby has special "!" notation for methods that modify the receiver

In Javascript:

var str = "Hello World";
str.toUpperCase();

console.log(str); // "Hello World"

In Python:

str = 'Hello World';
id(str) == id(str.upper()) # False

In other hand, with some array functions, PHP works with references. For those particular cases, if they are implemented in Primitives,i think we must stick with the actual PHP implementation.
Void or boolean methods must be implemented with fluent interface in Primitives

Here some of them:

array_*sort
array_*shift
array_push
array_pop
array_walk
shuffle

As some of parts of the Array / Collection methods are shared with String (ie: shuffle), it may be reasonable to share this behavior in order to produce a consistent API.

Primitives should provide developer with a static factory

Since Primitives have to live together with native scalar and arrays (as well as ArrayObject), it should be easy to instantiate a new Primitive object from an existing value.

That will prevent from writing such code in many methods:

/**
 * @param $string string|String
 */
public function whatever($string)
{
    if(!$string instanceof String) $string = new String($string);
}

Instead, we should do something like that:

/**
 * @param $string string|String
 */
public function whatever($string)
{
    // $string will be String, whatever its value was, unless it is not compatible
    $string = String::cast($string);
}

Recommend Projects

objective-php / primitives Goto Github PK