Download the PHP package bartfeenstra/fu without Composer

Functional PHP

This library provides tools to write more functional PHP code. Its concise and consistent API makes you more productive in different ways:

• Universal tools for processing iterables like arrays.
• Callback modification functions.
• Optional value types to aid with stronger typing and erorr handling.
• Shorthand exception handling.

Table of contents

1. Installation
2. About
3. Usage
   1. Iterators
   2. Operations
   3. Exception handling
   4. Predicates
   5. The Option type
   6. The Result type
   7. Partial function application
   8. Currying
4. Contributing
5. Development

About

This library was written to address several concerns:

• Provide a single, consistent API to the different iterable types in PHP, and the different operations available to the individual types: one API, any iterable, always associative, access to keys.
• Provide iterable processing operations that do not yet exist in PHP.
• Make writing closures quick and easy. Predicate factories can be used to generate common (filter) conditions.
• Allow developers to create functions that easily distinguish between different function outputs using optional value types. These can be used to solve problems like with json_decode(), which returns NULL in case of an error, or when it successfully decodes the JSON string null. It is impossible to distinguish between the different outcomes without additional code, such as option types.
• Use native PHP features where possible for improved interoperability and performance. Naming and parameter order follow the predominant conventions in PHP. This means all iterators implement \Iterator, and many PHP core functions are used internally.
• Add laziness where possible, so many operations are only applied to the iterator items you actually use.

Installation

Run composer require bartfeenstra/fu in your project's root directory.

Usage

To use any of the code, you must first import the namespaces at the top of your files:

Iterators

Traversable/iterable data structures can be converted to universal iterators:

Operations

The following operations work with iterator values, and even keys in the case of user-supplied callbacks:

each

Executes code for every value.

filter

Filters out values that do not match.

find

Tries to find a single matching value.

map

Converts all values individually.

mapKeys

Converts all keys individually.

reduce

Combines all values into a single one.

To terminate the reduction before all items have been processed, throw a TerminateReduction with the final carrier value.

fold

Combines all values into a single one, with a default start value.

To terminate the fold before all items have been processed, throw a TerminateFold with the final carrier value.

take

Takes n values.

takeWhile

Take as many consecutively matching values as possible from the beginning.

slice

Slices the values into a smaller collection.

min

Gets the lowest value.

max

Gets the highest value.

sum

Sums all values.

forever

Infinitely repeats the set of values.

zip

Combines the values of two or more iterables into tuples.

list

Converts all keys to integers, starting from 0.

listKeys

Uses keys as values, and indexes them from 0.

flip

Swaps keys and values, similarly to array_flip().

reverse

Reverses the order of the values.

first

Gets the first value.

last

Gets the last value.

empty

Checks if there are no values.

sort

Sorts items by their values.

sortKeys

Sorts items by their keys.

chain

Chains other iterables to an existing iterator, and re-indexes the values.

flatten

Flattens the iterables contained by an iterator into a single new iterator.

unique

Removes all duplicate values.

Exception handling

Complex try/catch blocks can be replaced and converted to Result easily:

Predicates

Predicates can be used with find(). They can be any callable that takes a single parameter and returns a boolean, but we added some shortcuts for common conditions. These functions take configuration parameters, and return predicates.

The Option type

In PHP, NULL signifies the absence of a value, but it is also used as a value itself. In such cases, an Option type helps to distinguish between NULL as a value, and no value at all.

The Result type

The Result type can be used to complement or replace exceptions. As such, it is returned by functions like try_except(). It represents success and a value, or an error.

Partial function application

Partial function application is the creation of a new function with zero or more parameters, based on an existing function, by fixing one or more of the arguments of the original function, before calling it. Practically speaking, it allows you to copy a function, and fill out some of the arguments before calling it. You can use this to quickly transform existing functions into anonymous functions that can be used as callbacks. In PHP, this is possible with any kind of callable (functions, methods, closures, ...).

Currying

Currying converts a single function with n parameters to n functions with one parameter each. Practically speaking, it allows you to copy a function, and fill out some of the arguments one at a time before calling it. You can use this to quickly transform existing functions into anonymous functions that can be used as callbacks. In PHP, this is possible with any kind of callable (functions, methods, closures, ...).

Contributing

Your involvement is more than welcome. Please leave feedback in an issue, or submit code improvements through pull requests.

The internet, and this project, is a place for all. We will keep it friendly and productive, as documented in our Code of Conduct, which also includes the project maintainers' contact details in case you want to report a situation, on behalf of yourself or others.

Development

Building the code

Run ./bin/build.

Testing the code

Run ./bin/test.

Fixing the code

Run ./bin/fix to fix what can be fixed automatically.

Code style

All PHP code follows PSR-2.