A framework is a tool that takes the pain out of building software. It should implement all the things that are common to most applications: the things that otherwise would have to be re-done for each new software project. That way, it prevents you from having to "re-invent the wheel" each and every time, while at the same time providing shortcuts for common problems and tasks.
While Agavi can, in theory, be used to build any type of application, its main focus lies in Web-based applications and Web services rather than standalone rich-client applications or daemons. That's because the internal execution flow is modeled around a typical HTTP request/response scenario, where an action is invoked upon a request, and the resulting response is built and returned before execution ends, just like any other PHP application.
Besides "doing the dishes" for you, a framework should also offer a very important factor during development: guidance. Agavi will, where necessary, actively prevent you from making the worst mistakes, keeping your code maintainable and giving you the comforting feeling that you're doing things the "right way."
Agavi abstracts common problems, and provides you, the developer, with a central, flexible solution that has evolved from the experiences and input of many users, as well as a single point of implementation you can comfortably override with custom code to create application-specific behavior.
As a result, you'll find yourself in the relaxing situation of not having to hack the framework core to achieve a certain goal. Often, a configuration parameter is all you need. And if not, the system's extreme extensibility guarantees that your custom implementation is only a couple of lines of code away - an important factor in the maintainability of an application, as it is not necessary to apply custom patches to the framework after each update.
Agavi comes with smart and versatile solutions to a great deal of problems that are often very difficult, time-consuming, or simply annoying to solve. Some of these include:
| It helps you build and maintain clean URLs. Agavi's routing implementation can not only map request URLs to actions, but also handles your web service requests, generates URLs for you, and much more. Read the chapter on routing for more information on advanced features such as route callbacks or how to read an HTTP Accept header and set an output type accordingly. |
| It validates your data and helps secure your code. Agavi can validate input submitted by the user, filter and normalize values, and make your application totally bullet-proof by only exposing validated data to your code, greatly lowering the risks of you or one of your developers using potentially unsafe data in your code. This applies to any potentially unsafe input, not just GET or POST data - files, cookies, and HTTP headers, among other input sources, will all be run through the validation system, and the single point of access to such data guarantees that you really only process data you have validated. |
| It takes the pain out of HTML forms. Agavi features a very clever approach to handling forms for you that does not rely on helpers or a specific template language to work. Not only will it re-populate the information the user entered when a form is shown again after submission, it also assigns classes to erroneous fields and their labels, and can even insert error messages into your form without any placeholders in the markup. Of course, you have full control over all aspects at any time, allowing you to pre-populate forms with information from your database or other sources. |
| It offers powerful features for globalization. Besides support for translating strings in different languages, Agavi comes with the ability to format and parse numbers, dates and currencies in over 250 different locales. It is aware of time zones, has extensive support for calendars and calendar operations, can give you a list of country names in the language (and script!) you like, and much, much more. |
Agavi's whole structure helps you a lot with designing and structuring your applications so that you get things right from the beginning. It encourages loose coupling, making it easy to hide implementational details from the parts of your code that should not have to worry about the "inner workings" of things, which also means that your code becomes very forward-compatible: whether you just want to modify the way your code talks to the database, or add a web service interface to your existing application, you will notice that your project already is structured in such a way that you do not have to go back and change existing things to make it happen.
Also, you'll be presented with certain best practices from the beginning, as Agavi's project skeletons are structured to help you avoid mistakes in the critical early phase of development where you build the foundation for your software. This ensures that you can fully benefit from all the features that made you choose Agavi in the first place.
And because Agavi follows the Model-View-Controller (MVC) architecture, your code automatically becomes highly efficient as the various parts are cleanly separated, making your application easily maintainable:
| The Model accesses your data. It might talk to a database, or to a web service, or use smoke signals to acquire the information it returns to you; the essential point is that the way the data is retrieved is absolutely irrelevant to the code that uses the model. So in the beginning, your application would use models that return "fake" dummy test data for rapid prototyping, and later, you will write the actual code that talks to a database. |
| The View presents your data. For Web sites, that typically means it renders an HTML document from one or more templates. But it could also build an RSS feed from the data it was given, or create a JSON data structure for the Ajax functionality of your application - it's all up to you! |
| The Controller contains the business logic: the code that talks to the model, transforms the data, performs necessary tasks and then prepares data for the View. In Agavi, we call this the Action. After it has finished its task, it tells the system which View to use to generate the output. |
This is the most important point about a framework. It should not lock you into a certain way of building your HTML output, or the way you deal with your database.
Of course, this is a bit of a moot point. You might argue that by using a framework in the first place, you're locking yourself in already - and you'd be right to insist! There is no doubt that by choosing a framework, you have to stick to it - not forever, of course, but you cannot simply cut and paste your code to port a project to a different framework. If a framework promises you that, they're either lying, or they don't deserve the label "framework" because their implementations are so low-level they provide only a simple toolkit (or, as they're called these days, a component library).
A framework can lock you in in many ways, like:
| Require you to use some object relational mapper tool to leverage the full potential of the framework. Many frameworks out there do this, and some people like that, while others don't. A good example is the infamous Ruby on Rails - a lot of it's glamour is due to it being strongly tied to the ActiveRecord ORM layer, and if you wish to use something else, some of the "Rails feeling" gets lost. |
Force you to use a certain template language in order to
be able to use all features. Many, many, many frameworks come
with helpers for everything you could possibly imagine, from
creating an opening <form> tag to inserting
stylesheets or even javascript effects. If you try to use the
template language of your choice, you have to replicate all this
stuff if you want to use it. And what's more, all these helpers
often do only 95% of what you want them to do, but not quite the
thing you had in mind. (Besides the obvious fact, of course,
that you might just outright hate the template language the
framework authors think is best for everyone, and that can ruin
the whole experience.) |
As you have probably guessed by now, Agavi tries hard not to lock you in to any of the above. You can use the template language you like, and everything just works - particularly the entire form handling system that was deliberately built in such a way that it is fully independent of any template language implementation.
And while Agavi offers integration for database object layers like Propel, you do not have to use such a layer. If you like, you may use AdoDB for database access, or the now common PDO, or even vanilla pgsql_* functions - it's all up to you. And if there is no adapter for your favorite layer bundled in the source distribution, chances are that someone has written one and shared it somewhere. And if not, (e.g., if it's your home-made database wrapper you have learned to love over the years), you can easily write a custom driver for it (and even that is not necessary, but of course highly recommended).
Sometimes, it's necessary to say "no." Many projects, over time, develop what's commonly known as "feature creep" or "featuritis". There are many things in the area of frameworks where you ask a thousand people for their opinion, just to get a thousand (or, in the worst case, even more) different answers. Not only must a framework decide not to implement a thousand different approaches in such a case, it's also very important to balance out precisely how much of a specific feature the framework should implement, or if it's better to leave it entirely up to the users.
A good example of this is any feature that is not within the scope of a framework, or that can work perfectly fine without being tied to the framework. A common feature is the ability to send e-mail. Smart frameworks don't have such a feature, because there already are many, many different libraries to choose from, many of which have matured over the course of years and as such are very stable and comfortable to use. There is simply no reason why a framework should be able to send e-mail, rotate image files, or come with a pre-made shopping cart module. Besides locking people in, every new feature that others solve better means increased activity on the support channels, derogating the quality of support for all users.
Many frameworks have so many helpers for so many things that do stuff in certain ways that people might easily become totally immersed in them. Users start to neglect what programming is really about: using one's own imagination and ingenuity. A framework should fuel the human thirst for knowledge and excellence, and not bury it under a pile of stuff targeted mainly at people who are too lazy to learn how things work - and learning how things work is an important factor in enabling people to leverage a tool's full potential. That's why this manual will, from time to time, delve into explaining the inner workings of Agavi, in case you're interested.