AGAVI UPGRADING INSTRUCTIONS
============================

Upgrading to 1.0 Series from 0.11 Series
========================================

Upgrading to Agavi 1.0 requires very little effort as the API remained identical.

It is recommended that you refer to the RELEASE_NOTES to see a list of deprecated elements, and change your application accordingly.

However, a couple of changes might affect your application:

Configuration file XML namespace changes
----------------------------------------
Legacy support for configuration files with no namespace (from 0.11 unstable versions) has been dropped.
That means <configurations> without xmlns="http://agavi.org/agavi/1.0/config" as the namespace will not work anymore.

New namespaces for all configuration files have been introduced, and envelope namespaces and actual content namespaces are now separate:
<a:configurations xmlns:a="http://agavi.org/agavi/config/global/envelope/1.0">
  <a:configuration>
    <handlers xmlns="http://agavi.org/agavi/config/parts/config_handlers/1.0">
      <handler pattern="%core.config_dir%/autoload.xml" class="AgaviAutoloadConfigHandler">
        <a:parameter name="foo">bar</a:parameter>
      </handler>
    </handlers>
  </a:configuration>
</a:configurations>

Old-style configuration files are still supported and will be converted to their new versions at runtime using XSL transformations. If you do not have ext/xsl enabled, you need to migrate your configuration files by hand.

Please refer to the documentation for a full list of configuration namespaces and their roles.

Routing Callbacks
-----------------
Routing has been changed as described in RELEASE_NOTES. If you run into trouble with your callback (this should usually only occur if you treat user parameters inside gen() in ways that do not trigger the new routing value object's __toString() method), implement AgaviILegacyRoutingCallback to restore "hard" backwards compatibility with previous versions. You will not be able to use routing value object features in this case.
It is important to note that whenever a callback's onMatched() method now returns false, the routing will explicitly call onNotMatched() again on the same callback instance. This behavior change is not configurable, and will not change even if you implement AgaviILegacyRoutingCallback. Please adjust your code accordingly.

Module and Action name Request Parameters
-----------------------------------------
By default, "module" and "action" parameters are not available anymore inside the request data. You are advised to use AgaviExecutionContainer::getModuleName() and AgaviExecutionContainer::getActionName() instead.
To restore previous behavior, set the request parameter "use_module_action_parameters" to true for <request> in factories.xml.

Validation Mode
---------------
AgaviValidationManager now assumes "strict" mode by default when no "mode" configuration parameter was given. Agavi code templates shipped with "strict" for production and "conditional" for development.* environments before, so you shouldn't be affected at all.
If you rely on the less secure "relaxed" mode being default (which you shouldn't), then you might need to adjust your factories.xml configuration.

Request method isolation
------------------------
Every Execution Container now has its own request method. This makes the reuse of Actions, particularly as slots, vastly more convenient. For containers created using any of the convenience methods
- AgaviExecutionContainer::createExecutionContainer()
- AgaviView::createForwardContainer()
- AgaviView::createSlotContainer()
the "current" container's request method is used for the new container. If your application previously relied on changing the global request method prior to spawning new containers as a workaround for the lack of this functionality in previous versions of Agavi, you need to adjust your code accordingly.

Template layer output availability
----------------------------------
By default, the output of the previous template layer is only available in $inner, not anymore through $slots['layername']. This can be changed through a configuration setting for the execution filter, but is strongly discouraged, as $inner is more portable (and also more logical).

Previously Deprecated Elements that have been removed
-----------------------------------------------------
The following methods and attributes were deprecated in Agavi 0.11 and have been removed in this following release:

- AgaviRequest::getActionAccessor(), use AgaviRequest::getParameter('action_accessor')
- AgaviRequest::getModuleAccessor(), use AgaviRequest::getParameter('module_accessor')
- AgaviTranslationManager::getClosestMatchingLocale(), superseded by AgaviTranslationManager::getLocaleIdentifier()
- AgaviTranslationManager::getLocaleFromIdentifier(), superseded by AgaviTranslationManager::getLocale()
- request attribute "matchedRoutes" in namespace "org.agavi.routing" is now called "matched_routes" to go with the general convention

Behavior changes resulting from bug fixes
-----------------------------------------
Some bugfixes resulted in minor behavioral changes and might require that you perform minor updates to your code:

- The Security Filter now always runs if "core.use_security" is enabled and per-
  forms the Action::isSecure() check itself.
  
  Previous behavior:
    This was previously done in the Execution Container, where the Security
    Filter was only added to the filter chain if the Action's isSecure() method
    returned true.
  
  New behavior:
    The Security Filter is now always run in the Action Fiter Chain, and no
    check against Action::isSecure() is performed in the Execution Container.
    Instead, the Security Filter is supposed to perform this check and act
    accordingly.
    The updated AgaviSecurityFilter instance does this by calling isSecure() on
    the action instance before performing any other checks against credentials
    or even authentication status, and will, if the method returns false, simply
    continue in the Filter Chain and leave the execute() method afterwards.
  
  This affects you if:
  - you have a custom Security Filter implementation or
  - you subclassed AgaviSecurityFilter to perform additional checks.
  
  What you need to do:
  - you need to add a check to see if the Action is flagged as secure, and if
    not, continue in the Filter Chain and leave the filter afterwards.

  Steps to update your code:
  - Open your custom Security Filter implementation.
  - As far to the top in execute() as possible, but in any case before you are
    making any checks against isAuthenticated() or even getCredentials(),
    insert code that corresponds to the following snippet:
  - Compare your change to the change made to Agavi's own Security Filter to
    determine whether or not your new implementation is correct. The update
    was made in trunk in revision 2267:
    http://trac.agavi.org/changeset/2267#file1
