File: documentation/README.txt

??Springy Framework

Copyright (c) 2007 Fernando Val

Active developer team:
    Fernando Val - fernando.val@gmail.com


### Documenta??o ###

- Sobre o framework:

O Springy foi projetado para ser um framework de desenvolvimentos de aplica??es
web em PHP no formato MVC. Ele ? uma evolu??o do FVAL PHP Framework,
desenvolvido por Fernando Val e Lucas Cardozo.


- O sistema MVC deste framework:

Os models (modelos) nada mais s?o que classes para tratamento de dados ou
fun??es gen?ricas ou de uso comum que n?o fazem parte do cerne do framework.
Nesse framework os models s?o tratados simplesmento como "classes propriet?rias"
e ficam armazenadas no diter?rio de classes propriet?rias (ver estrutura de
diret?rios). O framework possui uma classe de tratamento de bancos da qual voc?
poder? herdar suas classes para tratamento de tabelas em banco, simplesmente
crie suas classes extendendo a classe Springy\Model.

As views (vis?es), que s?o o resultado visual do processamento, s?o tratadas
como templates (modelos) e o sistema de gerenciamento de templates adotado nesse
framework ? a excelente biblioteca Smarty (http://smarty.net). Os templates s?o
armazenados no diret?rio de templates que pode ter m?ltiplos n?veis de acordo
com a necessidade do projeto.

As controladoras s?o os respons?veis pelo processamento espec?fico de cada
funcionalidade da aplica??o. As controladoras s?o armazenadas no diret?rio de
controladoras que, assim como o diret?rio de templates, pode conter m?ltiplos
n?veis para atender ?s necessidades do projeto.


- A estrurura de diret?rios do framework:

Como todo framework voltado para o desemvolvimento de aplica??es para web, o
diret?rio principal deste framework, ? o diret?rio raiz do site que, no caso do
servidor web Apache (http://www.apache.org) ? chamado de DOCUMENT_ROOT.

Dentro do diret?rio principal, est? o script de inicializa??o e respons?vel pela
carga da controladora adequado, al?m da localiza??o e carga das classes
propriet?rias e classes do framework que venham a ser utilizadas pela aplica??o,
que chamaremos simplemente de "inicializador". No pacote de distribui??o, o
inicializador vem denominado _Main.php.

Existe um arquivo index.php, que normalmente ? chamado pelo servidor web, mas
este script simplesmente mata a execu??o do PHP e retorna uma mensagem de acesso
inv?lido. Isso foi feito pensando que voc? ir? trabalhar com MOD_REWRITE do
Apache. Por esse motivo existe um arquivo .htaccess no diret?rio raiz da
aplica??o.

T?o importante quando o inicializador ? o script sysconf.php. Este script ? o
primeiro a ser carregado pelo inicializador e sua fun??o ? definir as
configura??es principais do cerne da aplica??o.

A seguir ser? explicada a fun??o de cada um dos diret?rios do framework e, para
isso, ser? utilizado o nome usado no pacote de distribui??o, pois nada impede
que a equipe de desemvolvedores os altere e regonfigure o framework.

Lista padr?o de diret?rios do framework:

    "app" : ? onde est?o os subdiret?rios do arquivos da aplica??o. Por quest?es
        de seguram?a, recomenda-se que este diret?rio esteja fora da ?rvore
        naveg?vel do sistema, se seu servidor web permitir o acesso a arquivos
        fora da ?rvore do www. Neste caso ? necess?rio ajustar o caminho no
        arquivo sysconf.php;

    "app/classes" : diret?rio onde s?o armazenadas as classes propriet?rias;

    "app/controllers" : diret?rio onde as controladoras s?o armazenados (pode
        conter subdiret?rios);

    "app/templates" : diret?rio onde s?o asmazenados os templates (pode conter
        subdiret?rios);

    "springy" : diret?rio onde est?o armazenados as classes e bibliotecas do
        framework;

    "conf" : diret?rio onde s?o armazenados os scripts de configura??o do
        sistema;

    "var/cached" : diret?rio onde a classe de templates ir? salvar as p?ginas
        cacheadas.

    "var/compiled" : diret?rio onde s?o asmazenados os templates compilados (o
        PHP deve ter direito de escrita dentro dele);

    "vendor" : diret?rio onde est?o armazenados as classes e bibliotecas de
        terceiros;

    "www" : ? o diret?rio onde est? o inicializador e o sysconf.php. Em alguns
        ambientes essa pasta tem nomes como httpdocs ou public_html;


- Como o sistema elege um script de controle (controladora):

Para determinar qual script de controle ser? carregado e executado, o sistema se
baseia na URI recebida. Ele desmembra o URI em segmentos e varre o diret?rio das
controladoras, come?ando pelo primeiro segmento do URI, da seguinte forma at?
que a primeira condi??o se revele verdadeira:

1) H? um script PHP de nome igual ao segmento:p, acrescido do sufixo ".page";

2) H? um subdiret?rio de nome igual ao segmento e dentro dele h? um script
denominado "index.page" e n?o mais segmentos.

Se nenhuma das condi??es acima se mostrarem verdadeiras e houver um subdiret?rio
de nome igual ao segmento e houver mais algum segmento, o sistema passa para o
pr?ximo segmento e refaz as verifica??es acima. Isso repete at? que um script
seja elegido controladora ou esgotem-se os segmentos do URI.

Caso o sistema tenha eleito uma controladora, ele a carrega para a mem?ria e a
partir da? faz as verifica??es de exe??o da controladora (veja o pr?ximo cap?tulo).

N?o havendo uma controladora eleita, a p?gia de erro 404 ? mostrada.


- Script de inicializa??o (bootstrap):

Antes de construir a controladora e fazer a chamada de seus m?todos, o framework
verifica a exist?ncia do script bootstrap.php, no diret?rio da aplica??o. Caso
esse arquivo exista, ser? carregado e executado. Este script serve como um
inicializador que sempre ? executado antes de qualquer controladora ser
carregada.


- A controladora e seus m?todos:

Eleito a controladora, o sistema cria uma classe com seu nome (o script ?
carregado automaticamente pelo sistema). Consequentemente o PHP ir? executar o
m?todo construtor da classe, que poder? ser usado pela equipe de desenvolvimento
para inicializar a vari?veis ou at? mesmo executar a principal a??o da
controladora, caso este n?o possua um m?todo para o tratamento do segmento de
URI seguinte (como veremos a seguir).

Tendo sucesso ao carregar a controladora, o sistema verifica se h? segmento de
URI seguinte e em caso afirmativo, busca por um m?todo de nome igual a este
segmento. Havendo este m?doto, o executa.

Caso a condi??o anterior n?o aconte?a, o sistema procura pelo m?todo _default e
o executa, se existir.


- Fim do processamento:

Ap?s os m?todos da controladora terminarem sua execu??o e devolverem o controle
para o inicializador, este faz os tratamentos finais e encerra a aplica??o.

Est? previsto para uma vers?o futura do framework o desenvolvimento de um hook
de finaliza??o a ser executado antes do sistema terminar.


- A biblioteca de classes:

O framework j? possuiu uma s?rie de classes que podem ser utilizadas pela equipe
de programadores a fim de facilitar e agilizar o desenvolvimento do projeto.

Para uma listagem completa das classes da biblioteca, acesse a documenta??o do
framework no seguinte enrede?o: http://framework.fval.net.br


- Direitos Autorais e Propriedade Intelectual:

Este framework ? distribu?do sob licen?a MIT.

Para detalhes de como utilizar esse framework, entre em contato com os autores.


- Hist?rico:

Veja o arquivo history.txt