Introduction


Collections

Enhances your daily PHP workflow with a hearty dose of functional programming in the spirit of Underscore.js.

Filelib

Filelib is a reusable file library component for PHP 5.3 applications.

Doctrine

Extends the core facilities of Doctrine ORM. Test fixture creation, a more robust internal API for repositories and query builders, and more!

Selenium2 WebDriver Server wrapper

Leverages Selenium2 and the Json Wire Protocol to make web testing easier. Also facilitates acceptance testing by having built-in screenshot capabilities. Build your documentation and run your acceptance tests in one step!


More solid documentation

We acknowledge getting started with most of our components isn't necessarily the easiest thing in the world. Even if the code is solid, users need and expect more. With components stemming mostly from internal development, getting documentation up to scratch is no trivial task, but we try.


Project overview

The Xi project contains multiple components, represented as repositories under the xi-project organization in Github. Each of these components has a designated maintainer, whose job is to upkeep quality and cohesion within the component. (In practice, this boils down to accepting pull requests.)

For contributing to an existing project, you should create a fork of a component and send your updates as pull requests on Github. If you want to contribute an entirely new component, you must assign the repository's ownership to the xi-project account, in which case the repository will be shown in the organization's Github page. You, of course, will be implicitly designated as the component's maintainer.

Guidelines

Tool support

Components should use Composer for autoloading and dependency management and Travis CI for Continuous Integration.

Directory layout

Components should follow a predictable structure.

/
README and LICENSE files
/library
The classes defined by your component.
/tests
Test case classes and bootstraps, with a directory structure mirroring /library.

Versioning

Tag release versions using git tags. Use semantic versioning:

  • A normal version number MUST take the form X.Y.Z where X, Y, and Z are integers. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically.
  • Bump the patch version if you apply small tweaks or include small additional features.
  • Bump the minor version if you make changes that break backwards compatibility.
  • Bump the major version if you make significant refactorings; however, if you're in major version 0, bumping the minor version should be sufficient.

For working with Git, we recommend the Git branching model, implemented by git-flow for your convenience.

Standards

Coding standards

We're not making our own - all projects should adhere to the PSR-2 coding standard. There's just a few points to make explicit.

  • Organize your classes under a single component-level namespace. This namespace should be the same as your component's name, eg. the classes in xi-collections reside under Xi\Collections.
  • For exceptions, create a component level marker interface, then create concrete classes that implement the marker interface and preferably extend a semantic PHP Exception type instead of the plain Exception class.
  • Do not define global functions and depend on them internally; the choice of which global functions to define should be for the component's user to make.

Architectural standards

  • Document at least your core architectural design decisions. Why was the component structured the way it is? What were your main considerations? Inability to understand your design motivations tends to induce a high WTF factor.
  • Do not depend directly on externals if you can avoid it. Instead, provide a suitable abstraction for integration with the externality. This allows for a greater potential degree of generalization and reusability.
  • Prefer TDD (or derivatives) and high code path coverage to praying it will work. If you can't have high code path coverage, have smoke tests in the very least.
  • Please stay DRY.

Other

Recommendations

Most of us use PhpStorm as our IDE. We are happy to recommend it.

PhpStorm


Contributor License Agreement

Due to corporate issues and a resulting requirement for copyright cleanliness, we have to require contributors to sign a license agreement. The agreement basically states that you allow us the use of code contributed by you, guaranteeing the project's legal safety. We'll be featuring an electronic form for you to sign the agreement in short order.

New BSD license

The New BSD license allows pretty much everything except the use of the contributors' names in forks without explicit permission. We chose it to guarantee that all code contributions can be salvaged should anything happen to the project, and to guarantee that the code is safe to use in proprietary, third-party projects.

This is how your LICENSE file should look.

Wait, what? Who are these guys?

The Xi project is not a legal entity, but the license's copyright statement has to reference at least one. We'd like Xi to be a community driven effort and not rest on corporate entities, so we used our actual names. The license states: "Copyright (c) 2012, Mikko Forsström, Mikko Hirvonen, Eevert Saukkokoski". These are the names of three guys with intent to improve the state of PHP.

The notation is merely symbolic; we represent the Xi project, and you aren't signing away anything you wouldn't expect to with a New BSD license.

That said, software licensing is not a simple beast, and none of us are legal experts. If you think there's something wrong with out licensing terms, contact us so we can sort it out.