[WIP] Initial Component Structure

.gitignore

@@ -0,0 +1,5 @@
+/vendor/
+composer.lock
+phpunit.xml
+/coverage/
+.php_cs.cache

.php_cs

@@ -0,0 +1,18 @@
+<?php
+
+return PhpCsFixer\Config::create()
+    ->setRiskyAllowed(true)
+    ->setRules(array(
+        '@PSR2' => true,
+        'psr4' => true,
+        'ordered_class_elements' => true,
+        'ordered_imports' => true,
+        'phpdoc_add_missing_param_annotation' => true,
+        'phpdoc_order' => true,
+        ))
+    ->setFinder(
+        PhpCsFixer\Finder::create()
+            ->exclude('tests/Fixtures')
+            ->exclude('vendor')
+            ->in(__DIR__)
+    );

composer.json

@@ -0,0 +1,17 @@
+{
+    "name": "phpol/string",
+    "description": "PHP Object Library String Component",
+    "type": "library",
+    "license": "MIT",
+    "minimum-stability": "stable",
+    "require": {},
+    "autoload": {
+        "psr-4": {
+            "OL\\String\\": "src/"
+        }
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^6.0",
+        "friendsofphp/php-cs-fixer": "^2.0"
+    }
+}

phpunit.xml.dist

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit backupGlobals="false"
+         backupStaticAttributes="false"
+         colors="true"
+         convertErrorsToExceptions="true"
+         convertNoticesToExceptions="true"
+         convertWarningsToExceptions="true"
+         processIsolation="false"
+         stopOnFailure="false">
+    <testsuites>
+        <testsuite name="String Component Test Suite">
+            <directory suffix="Test.php">./tests</directory>
+        </testsuite>
+    </testsuites>
+    <filter>
+        <whitelist processUncoveredFilesFromWhitelist="true">
+            <directory suffix=".php">./src</directory>
+        </whitelist>
+    </filter>
+    <logging>
+        <log type="coverage-clover" target="coverage/coverage.xml"/>
+        <log type="coverage-html" target="coverage/html"/>
+    </logging>
+</phpunit>

src/Contracts/Str.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace OL\String\Contracts;
+
+/**
+ * Interface Str.
+ *
+ * This interface should be the core interface for all string related classes.
+ * Other classes within this component should (when possible) extend this one.
+ */
+interface Str
+{
+    /**
+     * Str constructor.
+     *
+     * The constructor will enforce string type, since it can also receive
+     * another Str object (self) as it can be casted to string.
+     *
+     * @param string|Str $payload The actual string
+     */
+    public function __construct(string $payload);
+
+    /**
+     * Str objects should should be able to be cast as string.
+     *
+     * @return string The actual string
+     */
+    public function __toString();
+
+    /**
+     * Public method to retrieve the raw string contents of an object.
+     *
+     * @return string
+     */
+    public function contents();
+
+    /**
+     * Replace one or more entries from the given object with a given value
+     *
+     * @param array|string $search What to search for
+     * @param string $replace Replace with?
+     *
+     * @return Str
+     */
+    public function replace($search, string $replace);
+}

src/Str.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace OL\String;
+
+use OL\String\Contracts\Str as StrContract;
+
+/**
+ * Class Str.
+ *
+ * Basic manipulation of strings.
+ */
+class Str implements StrContract
+{
+    /**
+     * @var string Raw string content
+     */
+    protected $payload;
+
+    /**
+     * Str constructor.
+     *
+     * The constructor will enforce string type, since it can also receive
+     * another Str object (self) as it can be casted to string.
+     *
+     * @param string|StrContract $payload The actual string
+     */
+    public function __construct(string $payload)
+    {
+        // casts the payload as string and them assign on class scope
+        $this->payload = (string) $payload;
+    }
+
+    /**
+     * Str objects should should be able to be cast as string.
+     *
+     * @return string The actual string
+     */
+    public function __toString()
+    {
+        return $this->contents();
+    }
+
+    /**
+     * Public method to retrieve the raw string contents of an object.
+     *
+     * @return string
+     */
+    public function contents()
+    {
+        return $this->payload;
+    }
+
+    /**
+     * Replace one or more entries from the given object with a given value
+     *
+     * @param array|string $search What to search for
+     * @param string $replace Replace with?
+     *
+     * @return StrContract Object instance with the replaced text.
+     */
+    public function replace($search, string $replace)
+    {
+        return $this->factory(str_replace($search, $replace, $this));
+    }
+
+    /**
+     * Factories a new StrContract object.
+     *
+     * @param string $str Instance to be factory from
+     *
+     * @return StrContract
+     */
+    protected function factory(string $str)
+    {
+        return new self($str);
+    }
+}

tests/StrTest.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace OL\String;
+
+use OL\String\Contracts\Str as StrContract;
+use PHPUnit\Framework\TestCase;
+
+class StrTest extends TestCase
+{
+    /**
+     * This test should instantiate with success from a string
+     */
+    public function test_instantiable_with_string()
+    {
+        // create a new instance
+        $str = new Str('foo value');
+
+        // make sure it is implementing the main contract
+        $this->assertInstanceOf(StrContract::class, $str);
+    }
+
+    /**
+     * This test should determine if an object of Str can be cast as a string.
+     */
+    public function test_object_can_be_cast_as_string()
+    {
+        // create a new instance
+        $str = new Str('foo bar baz');
+
+        // assert the cast value of the object is equals the initially given string.
+        $this->assertEquals('foo bar baz', (string) $str);
+    }
+
+    /**
+     * This test should prove an Str object can be created from another
+     * Str object.
+     */
+    public function test_instantiable_with_str_object()
+    {
+        // create an initial instance
+        $initialStr = new Str('foo bar');
+
+        // create an instance passing not directly a string but an StrContract object.
+        $str = new Str($initialStr);
+
+        // assets contract implementation.
+        $this->assertInstanceOf(StrContract::class, $str);
+        // assets the contents are correctly passed between instances.
+        $this->assertEquals('foo bar', $str->contents());
+    }
+
+    /**
+     * Test replacement of parts of text, using a single string
+     */
+    public function test_replace_single_string()
+    {
+        $str = new Str('foo bar');
+
+        $replaced = $str->replace('bar', 'baz');
+
+        $this->assertEquals('foo baz', $replaced);
+    }
+
+    /**
+     * Test replacement of parts of text, using a multiple search strings
+     */
+    public function test_replace_multiple_string()
+    {
+        $str = new Str('foo bar baz');
+
+        $replaced = $str->replace(['bar', 'baz'], 'foo');
+
+        $this->assertEquals('foo foo foo', $replaced);
+    }
+
+    /**
+     * Test replacement of parts of text, using a multiple search strings and objects
+     */
+    public function test_replace_multiple_string_with_objects()
+    {
+        $str = new Str('foo bar baz');
+
+        $replaced = $str->replace([new Str('bar'), 'baz'], 'foo');
+
+        $this->assertEquals('foo foo foo', $replaced);
+    }
+}