Project Goals

Clear and Consistent

Solar classes should be easy to comprehend and consistently implemented.

Nobody wants to learn how to use another system; most developers prefer to spend their time writing their own tools, not conforming to someone else's ideas. I think that is because most code is written without taking the audience into consideration (the "audience" being other developers).

Because reading code from other developers is a learning experience, all Solar classes are written as a teaching experience. This means that Solar classes are written as simply and clearly as possible without any tricky or obtuse techniques.

Solar classes consistently use shared implementation ideas and are written according to a common style guide. Each component in the project "looks" and "feels" like it is part of an overarching and consistent design. (The book The Mythical Man-Month calls this aspect "conceptual integrity".)

Finally, Solar classes are named and structured according the vocabulary established by Patterns of Enterprise Application Architecture. This means that anyone familiar with design pattern terminology should be able to quickly discern which classes perform which functions.

Teaching/Learning Community

The community of Solar users should be respectful and cordial to encourage problem-solving and idea exchange, not ego-boosting, point-scoring, or one-upmanship.

The social aspect of development is often overlooked or under-rated. In Solar, we recognize that support and encouragement from other developers is a good and necessary component of successful projects. Again, this is because all development is a learning experience, so we should foster a teaching environment for that experience.

Thus, while providing a mailing list and wiki for collaboration, we want to maintain a polite and cordial atmosphere both for established developers and for new users. The primary social rule in all public communication around Solar is to be nice.

Global Collaboration

Solar classes should be fully name-spaced, self-contained, and localizable.

Although English is the de-facto language of developers worldwide, end-users don't want to see English-only labels, buttons, and text. Solar classes come with easy built-in text localization so that it's easy to translate into languages other than English.

Solar is probably not the only PHP class library you are going to use. Because Solar classes are always named with a Solar_ prefix, you never need to worry about name conflicts or collisions from other libraries. Similarly, any classes you build for yourself should have a unique namespace prefix (often called the Vendor_ prefix in the documentation).

Solar-based applications should be self-contained; this means no external dependencies, and all internal dependencies should resolve themselves. In practice, this means that all Solar classes are distributed in a single package.

Separation of Concerns

Solar classes should adhere to model, view, and controller separation.

Only one Solar class generates output in the normal course of execution: the Solar_View class. Other Solar classes may access, manipulate, and return data, but they may not output it; output is solely in the realm of the "view" in a model/view/controller application, and Solar_View is the only "view" class in the standard Solar distribution.

In addition, this makes it easy to write applications that are theme-aware. Because all output passes through a template, the template can be modified to present the data in any way preferred by the developer.

(Note that we said "in the normal course of execution" above; exceptions and various debug tools will generate output, but of course that's not the normal course. :-)

Useful Documentation

Solar classes should be well-documented; this means real narrative documentation on how to use Solar, not just class descriptions.

Because developers generally find it less-rewarding, initially, to spend time learning someone else's code, all Solar packages will have extensive end-user documentation. Solar classes also have extensive inline comments to guide the reader while examining code, and we aim to provide extensive narrative documentation as well via this site.

Solid Implementation

  • Runs cleanly under PHP 5 with E_ALL and E_STRICT error reporting;

  • Class- and object-oriented, not function-oriented, with full name-space separation;

  • Provides easy-to-use secure-programming elements and a secure foundation to work from;

  • Provides a common means for loading, instantiating, and configuring classes automatically;

  • Provides a common configuration system for Solar classes and for applications built on Solar components;

  • Provides basic library class components (authentication, database, cache, log, debug, forms, validation, etc) commonly used in web applications;

  • Provides easy application distribution in shared environments.