Download the PHP package 8fold/php-shoop without Composer

8fold Shoop for PHP

Shoop is a horizontally-consistent interface into PHP, whereas PHP could be described as a vertically-consistent interface into C.

Shoop is built on 8fold Foldable allowing for ubiquitous construction of data objects.

Installation

Usage

Contrived examples...live examples coming soon and available in the tests folder.

Apply a single filter.

Pipe multiple filters.

Nesting pipes and filters. (Variation on part of the PlusAt Filter.)

Fluent using method chaining.

Types and type juggling

Shoop defines abstract and concrete types.

Abstract Shoop types map directly to PHP types.

Concrete Shoop types:

1. MUST be self-defined as what they are or are like as opposed to what they are not.
2. MUST juggle reasonably to all other Shoop concrete types except object.

Note: Rather than being implemented as PHP classes, Shoop types are interpretations of PHP types you implement. Shoop types facilitate type juggling, transformations, and the application of filters.

Filters

Filters are PHP classes inheriting from the Shoop abstract filter and implementing the interface methods required by that inheritance.

Filters generally act as a bridge between Shoopland and PHP. They can be viewed as low-level functions used to manipulate PHP types. For a manipulation to become a filter, it MUST meet AT LEAST three of the following:

1. Used at least three times in one or more production project(s), which MAY include Shoop itself. ex. Reversed::fromBoolean
2. Fully testing the proposed filter results in testing multiple other filters. ex. IsEmpty::fromTuple
3. The proposed filter DOES NOT require testing because it uses PHP directly. ex. IsEmpty::fromString
4. The proposed filter DOES NOT require testing because it uses approved filters that do not require testing. ex. AsBoolean::*

Note: If the fourth item is used as a reason for the proposed filter to be approved, it SHOULD be accompanied by a specific reason. For example, the AsBoolean filter facilitates juggling to that concrete type and returns the result of IsNotEmpty, which returns the result of IsEmpty that is Reversed. Neither AsBoolean nor IsNotEmpty require testing; however, it is a DRY way of implementing the PHP bool casting operation for most PHP types.

By complying with the previous, the following requirement should be met automatically:

1. The proposed filter MUST be fully tested, directly or inderectly.

Note: With Shoop, objects are fully specifiable PHP types, as you can implement their representation as any and all Shoop-supported PHP types.

Deviations from PHP

In order to make Shoop easy to adopt we try not to deviate too much from what you're accustomed to. The following details the known deviations from PHP standard behavior:

Performance

Each test we write covers performance for speed and memory usage.

When it comes to speed, our goal is that every filter can be applied and returned in less than one millisecond (represented as 1.0 in our tests).

Our starting point for speed checks is one microsecond (0.001 in our tests). If a test goes over one microsecond, but less than 5 microseconds, we bump the speed check by one microsecond (ex. 0.001001 becomes 0.002) while leaving the previous, shorter run(s) as comment notes. If a test goes over five microseconds (0.005) we switch to 10 microsecond intervals (ex. 0.005 becomes 0.01). In all other cases, we round up to the nearest 10 microsecond mark (ex. 0.010001 becomes 0.02).

When it comes to memory, our goal is that every filter can be applied and returned using less than 1 kilobyte of memory (1 in our tests). This will be based somewhat on what is passed to the filter. Our tests are measured with a bare miminum value passed in to verify the test delivers the expected result.

Our tests are also written using the filter pattern:

Project

Goals

The primary goals for Shoop, in no particular order:

• Plain language (approachable): PHP is pretty accessible to new developers who maybe don't have a computer science background; Shoop continues this theme.
• Syntactically and semantically light: PHP is understandably heavy on syntax (special characters to help the parser) and semantically expansive when it comes to capabilities (short function names, but many of them). We review Filters and capabilities based on production need, not gut feel and "because we can."
• Immutable: Whenever possible, we return new instances and values as opposed to altering the state.
• Type-safe: The flexibility of Shoop means we don't check types every step along the way, but do check types before returning the result of a request.
• Defer processing: Whenever possible we defer processing until the last possible moment.
• Ubiquity across types: We favor a small number of filters that can then be minimally configured using arguments.
• DRY (don't repeat yourself): We strive to leverage capabilities already available in Shoop rather than implementing PHP solutions; most of the Filters came from developing a different Filter.
• Let nothing mean nothing: As developers, we spend a lot of time accounting for, working around, and defending against things that represent nothing. null is arguably the most known thing representing nothing, Shoop doesn't use nor account for null. false also equates to zero, which represents nothing. The idea that zero represents nothing is the primary argument for Shoop arrays to start at one, as requesting the "nothing index" should always result in receiving nothing...something cannot be contained by nothing.

An oft cited criticism of PHP is its inconsistent API. PHP's creator, Rasmus, has explained it this way (paraphrased):

PHP is perfectly consistent, just not the way you expect. It's vertically consistent. So, for every function in PHP, if you look at what's underneath it, the libc function under some of the string functions, for example, the argument order and naming matches what they're built upon. So, there's not consistency horitzontally, but there's perfect consistency vertically digging down into the stack.

If you use classes from the Illuminate Support portion of Laravel or some of the Symfony Components, you're familiar with the desire for horizontally consistent APIs problem (even beyond PHP itself).

While this immplementation is language-specific, the fundamental concepts, patterns, and naming strive to be language agnostic.

PHP is extremely simple for new developers, Shoop follows this tradition.

Contributing

For more general advice see our Contributing documentation.

What's in a name?

Shoop, as an acronym, points to the insipirations of the library:

• Swift, Smalltalk, and Squeak;
• Haskell (functional programming and immutability);
• Object-Oriented (encapsulation, composition, and communication); and
• Procedural (sequential, logical programming).

Shoop, as a word, is akin to "photoshopping" (and sounds nicer than "Foops").

Shoop, as a name, is the title of a song by Salt-N-Pepa released in 1993 and used in the first installment of the Deadpool franchise in 2016.

Other

• Versioning
• Governance

History

This library has been under development since the beginning of 2019 and has been used in the majority of 8fold projects since the middle of 2019. With every new project created we tried to go without it but found ourselves becoming annoyed, which is why we've decided to make it a more formal project and library consumable by others.

We offer multiple Interfaces and default Implementations for juggling between the supported, concrete types. Each interface offers two methods: one returns an object implementing the interface and the other returns the PHP types. The former are prefixed with "as" for use in Fluent Interfaces. The latter are prefixed with "ef" and can be thought of as similar to PHP Magic Methods which are prefixed with a double-underscore (__).

?? - abstract and concrete filters - ??

• Abstract filters use other filters to generate the output.
• Concrete filters DO NOT use other filters to generate the output.

PHP deviations

Boolean

Number and integer

Should array to tuple be the PHP default for array to object?? Reduces deviations.

String

Dictionary, tuple, and JSON

Ditionary and tuple deviate from PHP in similar ways, syntax might be different.

Note: A JSON string is converted to a Tuple, and a Tuple is converted to a Dictionary.

Note: The default implementation of the PHP JsonSerialize interface results in the PHP type being converted to a Shoop Tuple, then being encoded.

Array

Should array to tuple be the PHP default for array to object?? Reduces deviations. Accessing those properties doesn't work as expected.

ex. $object = object(["0"] => 1, ["1"] => 2):

• $object->0 = parse error
• $object->"0" = parse error
• $object->{0} = expected behavior

Object

ex. $using = new class {}