diff --git a/docs/api/api.md b/docs/api/api.md index 53c244afa5..47f344509f 100644 --- a/docs/api/api.md +++ b/docs/api/api.md @@ -1,5 +1,3 @@ - - # API An Application Programming Interface (API) allows you to connect your code to eZ Platform. @@ -8,7 +6,7 @@ From the eZ Blog: [How would you explain what an API is to your mom](http://ez. eZ Platform offers two APIs: -1. The [REST API](https://doc.ez.no/display/DEVELOPER/REST+API+Guide) allows you to interact with an eZ Platform installation using the HTTP protocol, following a REST interaction model -2. The [Public (PHP) API](https://doc.ez.no/display/DEVELOPER/Public+API+Guide) exposes a Repository which allows you to create, read, update, manage and delete all objects available in eZ Platform, first and foremost content, but also related objects like sections, locations, content types, content types groups, languages and so on. +1. The [REST API](rest_api_guide.md) allows you to interact with an eZ Platform installation using the HTTP protocol, following a REST interaction model +2. The [Public (PHP) API](public_php_api.md) exposes a Repository which allows you to create, read, update, manage and delete all objects available in eZ Platform, first and foremost content, but also related objects like sections, locations, content types, content types groups, languages and so on. -There is also a [JavaScript API Client](JS-Client_31429579.html), useful for working with eZ Platform as a [headless CMS](http://ez.no/Blog/Content-as-a-Service-CaaS-Decoupled-CMS-and-Headless-CMS-101). +There is also a [JavaScript API Client](js_client.md), useful for working with eZ Platform as a [headless CMS](http://ez.no/Blog/Content-as-a-Service-CaaS-Decoupled-CMS-and-Headless-CMS-101). diff --git a/docs/api/extending_the_rest_api.md b/docs/api/extending_the_rest_api.md index 0067edce5e..1092bafc50 100644 --- a/docs/api/extending_the_rest_api.md +++ b/docs/api/extending_the_rest_api.md @@ -1,5 +1,3 @@ - - # Extending the REST API The eZ Platform REST API comes with a framework that makes it quite easy to extend the API for your own needs. @@ -152,11 +150,11 @@ class Hello extends ValueObjectVisitor } ``` -Do not hesitate to look into the built-in ValueObjectVisitors, in ` eZ/Publish/Core/REST/Server/Output/ValueObjectVisitor `, for more examples. +Do not hesitate to look into the built-in ValueObjectVisitors, in `eZ/Publish/Core/REST/Server/Output/ValueObjectVisitor`, for more examples. ### Cache handling -The easiest way to handle cache is to re-use the ` CachedValue ` Value Object. It acts as a proxy, and adds the cache headers, depending on the configuration, for a given object and set of options. +The easiest way to handle cache is to re-use the `CachedValue` Value Object. It acts as a proxy, and adds the cache headers, depending on the configuration, for a given object and set of options. When you want the response to be cached, return an instance of CachedValue, with your Value Object as the argument. You can also pass a location id using the second argument, so that the Response is tagged with it: @@ -249,7 +247,7 @@ You can register newly added resources so that they show up in the REST root res New resources can be registered with code like this: -``` +``` yaml ez_publish_rest: system: default: diff --git a/docs/api/field_type_api_and_best_practices.md b/docs/api/field_type_api_and_best_practices.md index 31dbc46ef9..1387f0e409 100644 --- a/docs/api/field_type_api_and_best_practices.md +++ b/docs/api/field_type_api_and_best_practices.md @@ -1,4 +1,3 @@ - # Field Type API & best practices eZ Platform can support arbitrary data to be stored in the fields of a content item. In order to support custom data, besides the standard data types, a developer needs to create a custom **Field Type**. @@ -7,7 +6,7 @@ The implementation of a custom Field Type is done based on the Field Type SPI an In order to provide custom functionality for a Field Type, the SPI interacts with multiple layers of the eZ Platform architecture, as shown in the following diagram: - ![](docs/api/img/field_type_overview.png) +![](img/field_type_overview.png) On the top layer, the Field Type needs to provide conversion from and to a simple PHP hash value to support the REST API. The generated hash value may only consist of scalar values and hashes. It must not contain objects or arrays with numerical indexes that aren't sequential and/or don't start with zero. @@ -21,16 +20,15 @@ On the bottom level, a Field Type can additionally hook into the Persistence SPI The following sequence diagram visualizes the process of creating a new `Content` across all layers, especially focused on the interaction with a `FieldType`. -![](docs/api/img/create_content_sequence.png) +![](img/create_content_sequence.png)   - In the next lines/pages, this document explains how to implement a custom Field Type based on the SPI and what is expected from it. As a code example, please refer to the Url FieldType, which has been implemented as a reference. ## Public API interaction The interaction with the Public API is done through the interface `eZ\Publish\SPI\FieldType\FieldType`. A custom Field Type must provide an implementation of this interface. In addition, it is considered best practice to provide a value object class for storing the custom field value provided by the Field Type. -## FieldDefinition handling +### FieldDefinition handling In order to make use of a custom Field Type, the user must apply it in a `eZ\Publish\API\Repository\Values\ContentType\FieldDefinition` of a custom Content Type. The user may in addition provide settings for the Field Type and a validator configuration.  Since the Public API cannot know anything about these, their handling is delegated to the Field Type itself through the following methods: @@ -56,7 +54,7 @@ It is important to note that while the schema definitions of the `FieldType` may This will also apply to all user interfaces and the REST API, which therefore must provide extension points to register handling code for custom `FieldType`. These extensions are not defined, yet. -## Name of the Field Type +#### Name of the Field Type If you implement Nameable as an extra service, and register this Service using the tag `nameable`, the method `{FieldType}Nameable->getFieldName()` will be used to retrieve the name. @@ -74,9 +72,7 @@ Otherwise the regular `{FieldType}->getName()` method is used. - {name: ezpublish.fieldType.nameable, alias: ezobjectrelation} ``` -  - -## Value handling +### Value handling A field type needs to deal with the custom value format provided by it. In order for the public API to work properly, it delegates working with such custom field values to the corresponding Field Type. The `SPI\FieldType\FieldType` interface therefore provides the following methods: @@ -90,15 +86,15 @@ Note: The method must assert structural consistency of the value, but must not v Through settings, the `FieldType` can specify, that the user may define a default value for the `Field` of the type. If no such default is provided by the user, the `FieldType` itself is asked for an "empty value" as the final fallback. The value chain for a specific field is therefore like this, when a `Field` of the `FieldType` is filled out: - 1. Is a value provided by the filling user? - 2. Is a default provided by the `FieldDefinition`? - 3. Take the empty value provided by the `FieldType` +1. Is a value provided by the filling user? +2. Is a default provided by the `FieldDefinition`? +3. Take the empty value provided by the `FieldType` `validate()` In contrast to `acceptValue()` this method validates the plausibility of the given value, based on the `FieldType` settings and validator configuration, stored in the corresponding `FieldDefinition`. -## Storage conversion +### Storage conversion As said above, the value format of a `FieldType` is free form. However, in order to make eZ Publish store the value in it's database, it must comply to certain rules at storage time. To not restrict the value itself, a `FieldValue` must be converted to the storage specific format used by the Persistence SPI: `eZ\Publish\SPI\Persistence\Content\FieldValue`. After restoring a Field of `FieldType`, the conversion must be undone. The following methods of the `FieldType` are responsible for that: @@ -118,7 +114,7 @@ The data to be stored in the eZ Publish database. This may either be a scalar va `$externalData` -The arbitrary data stored in this field will not be touched by any of the eZ Publish components directly, but will be hold available for [Storing external data](../api/Field_Type_API_and_best_practices.md#Storing-external-data). +The arbitrary data stored in this field will not be touched by any of the eZ Publish components directly, but will be hold available for [Storing external data](#storing-external-data). `$sortKey` @@ -151,7 +147,7 @@ array(  This example from the `Url` field type shows that the field type will always return two indexable values, both strings. They have the names `url` and `text` respectively. -## Search Field Values +### Search Field Values The search field values, returned by the `getIndexData` method are simple value objects consisting of the following properties: @@ -167,7 +163,7 @@ The value of the field An `eZ\Publish\SPI\Persistence\Content\Search\FieldType` instance, describing the type information of the field. -## Search Field Types +### Search Field Types There are bunch of available search field types, which are automagically handled by our Search backend configuration. When using those there is no requirement to adapt , for example, the Solr configuration in any way. You can always use custom field types, though, but these might require re-configuration of the search backend. For Solr this would mean adapting the schema.xml. @@ -209,7 +205,7 @@ Field used for IDs. Basically acts like the string field, but will not be querie Custom field, for custom search data types. Will probably require additional configuration in the search backend. -## Configuring Solr +### Configuring Solr As mentioned before, if you are using the standard type definitions **there is no need to configure the search backend in any way**. Everything will work fine. The field definitions are handled using `dynamicField` definitions in Solr, for example. @@ -249,9 +245,9 @@ Must delete external data for the given `Field`, if exists. See search service -Each of the above methods receive a $context array, which contains information on the underlying storage and the environment. This context can be used to store data in the eZ Publish data storage, but outside of the normal structures (e.g. a custom table in an SQL database). Note that the Field Type must take care on it's own for being compliant to different data sources and that 3rd parties can extend the data source support easily. For more information about this, take a look at the [Best practices](../api/Field_Type_API_and_best_practices.md#Best-practices) section. +Each of the above methods receive a $context array, which contains information on the underlying storage and the environment. This context can be used to store data in the eZ Publish data storage, but outside of the normal structures (e.g. a custom table in an SQL database). Note that the Field Type must take care on it's own for being compliant to different data sources and that 3rd parties can extend the data source support easily. For more information about this, take a look at the [Best practices](#best-practices) section. -### Legacy Storage conversion +## Legacy Storage conversion The `FieldType` system is designed for future storage back ends of eZ Publish. However, the old database schema (*Legacy Storage*) must still be supported. Since this database cannot store arbitrary value information as provided by a `FieldType`, another conversion step must take place if the Legacy Storage is used. @@ -277,13 +273,13 @@ Converts the other way around. Returns the storage column which is used for indexing. -## Registering a converter +### Registering a converter The registration of a `Converter` currently works through the `$config` parameter of `eZ\Publish\Core\Persistence\Legacy\Handler`. See the class documentation for further details. -  +!!! note -For global service container integration, see [Register Field Type](../api/Field_Type_API_and_best_practices.md#Register-field-type). + For global service container integration, see [Register Field Type](#register-field-type). ## REST API interaction @@ -313,7 +309,7 @@ Converts FieldType validator configuration to a simple hash format. Converts the other way around. -## Extension points +### Extension points Some `FieldTypes` will require additional processing, for example a `FieldType` storing a binary file, or one having more complex settings or validator configuration. For this purpose specific implementations of an abstract class `eZ\Publish\Core\REST\Common\FieldTypeProcessor` are used. This class provides following methods: @@ -343,13 +339,13 @@ Performs manipulations on a outgoing validator configuration hash, previously ge Base implementations of these methods simply return the given hash, so you can implement only the methods your `FieldType` requires. Some `FieldTypes` coming with the eZ Publish installation already implement processors and you are encouraged to take a look at them. -For details on registering a `FieldType` processor, see [Register Field Type](../api/Field_Type_API_and_best_practices.md#Register-field-type). +For details on registering a `FieldType` processor, see [Register Field Type](#register-field-type). ## Best practices In this chapter, best practices for implementing a custom FieldType are collected. We highly encourage following these practices to be future proof. -## Gateway based Storage +### Gateway based Storage In order to allow the usage of a `FieldType` that uses external data with different data storages, it is recommended to implement a gateway infrastructure and a registry for the gateways. In order to ease this action, the Core implementation of `FieldType` s provides corresponding interfaces and base classes. These can also be used for custom field types. @@ -373,7 +369,7 @@ This protected method is used by the implementation to retrieve the correct `Sto As a reference for the usage of these infrastructure, the Keyword, Url and User types can be examined. -## Settings schema +### Settings schema It is recommended to use a simple hash map format for the settings schema retured by eZ\\Publish\\SPI\\FieldType\\FieldType::getSettingsSchema(), which follows these rules: @@ -397,9 +393,7 @@ array( ); ``` -  - -## Validator schema +### Validator schema The schema for validator configuration should have a similar format than the settings schema has, except it has an additional level, to group settings for a certain validation mechanism: @@ -428,13 +422,13 @@ array( ## Registering a Field Type -To register a Field Type, see [Register Field Type](../api/Field_Type_API_and_best_practices.md#Register-field-type). +To register a Field Type, see [Register Field Type](#register-field-type). To be integrated in unit and integration tests, Field Types need to be registered through the `service.ini` in `eZ/Publish/Core/settings`. ## Templating -A FieldType always need a piece of template to be correctly displayed. See [Field Type template](../guide/Field_Type_API_and_best_practices.md#Field-Type-template). +A FieldType always need a piece of template to be correctly displayed. See [Field Type template](#field-type-template). ## Testing @@ -445,15 +439,13 @@ A FieldType always need a piece of template to be correctly displayed. See [Fie For both test environments, infrastructure is already in place, so that you can easily implement the required tests for your custom `FieldType` -## Persistence SPI +### Persistence SPI This type of integration test ensures, that a Field Type stores its data properly on basis of different Persistence SPI implementations. -  +!!! note -**Note:** By now, only the Legacy Storage implementation exists. - -  + By now, only the Legacy Storage implementation exists. The integration tests with the Persistence SPI can be found in `eZ\Publish\SPI\Tests\FieldType`. In order to implement a test for your custom `FieldType`, you need to extend the common base class `eZ\Publish\SPI\Tests\FieldType\BaseIntegrationTest` and implement it's abstract methods. As a reference the `KeywordIntegrationTest`, `UrlIntegrationTest` and `UserIntegrationTest` can deal. @@ -465,24 +457,22 @@ $ phpunit -c phpunit.xml eZ/Publish/SPI/Tests/FieldType in order to run all `FieldType` tests. -## Public API +### Public API On a second level, the interaction between an implementation of the Public API (aka the Business Layer) and the Field Type is tested. Again, there is a common base class as the infrastructural basis for such tests, which resides in `eZ\Publish\API\Repository\Tests\FieldType\BaseIntegrationTest`. -  - -Note that the In-Memory stubs for the Public API integration test suite, do not perform actual Field Type calls, but mainly emulate the behavior of a Field Type for simplicity reasons. - -If your Field Type needs to convert data between `storeFieldData()` and `getFieldData()`, you need to implement a `eZ\Publish\API\Repository\Tests\Stubs\PseudoExternalStorage` in addition, which performs this task. Running the tests against the Business Layer implementation of the Public API is not affected by this. +!!! note  + Note that the In-Memory stubs for the Public API integration test suite, do not perform actual Field Type calls, but mainly emulate the behavior of a Field Type for simplicity reasons. + If your Field Type needs to convert data between `storeFieldData()` and `getFieldData()`, you need to implement a `eZ\Publish\API\Repository\Tests\Stubs\PseudoExternalStorage` in addition, which performs this task. Running the tests against the Business Layer implementation of the Public API is not affected by this. ## Field Type template -## Defining your Field Type template +### Defining your Field Type template -In order to be used by [`ez_render_field()` Twig helper](../guide/twig_functions_reference.md), you need to define a **template containing a block** dedicated to the Field display. +In order to be used by [`ez_render_field()` Twig helper](../guide/content_rendering.md#twig-functions-reference), you need to define a **template containing a block** dedicated to the Field display. This block consists on a piece of template receiving specific variables you can use to make the display vary. @@ -498,8 +488,7 @@ You will find examples with built-in Field Types in [EzPublishCoreBundle/Resourc By convention, your block **must** be named `_field`. -## Exposed variables - +### Exposed variables | Name | Type | Description | |------|------|-------------| @@ -510,20 +499,17 @@ By convention, your block **must** be named `_field`. |parameters | hash | Options passed to ez_render_field() under the parameters key | |attr | hash | The attributes to add the generate the HTML markup. Contains at least a class entry, containing -field | - -## Reusing blocks +### Reusing blocks To ease Field Type template development, you can take advantage of all defined blocks by using the [block() function](http://twig.sensiolabs.org/doc/functions/block.html). You can for example take advantage of `simple_block_field`, `simple_inline_field` or `field_attributes` blocks provided in [content\_fields.html.twig](https://github.com/ezsystems/ezpublish-kernel/blob/master/eZ/Bundle/EzPublishCoreBundle/Resources/views/content_fields.html.twig#L413). -Warning +!!! caution -To be able to reuse built-in blocks, **your template must inherit from `EzPublishCoreBundle::content_fields.html.twig`**. + To be able to reuse built-in blocks, **your template must inherit from `EzPublishCoreBundle::content_fields.html.twig`**. -## Registering your template - -  +### Registering your template To make your template available, you must register it to the system. @@ -540,30 +526,26 @@ ezpublish: priority: 10 ``` -You can define these rules in a dedicated file instead of `app/config/ezplatform.yml`. Read the [cookbook recipe to learn more about it](../cookbook/Importing_settings_from_a_bundle.md). +You can define these rules in a dedicated file instead of `app/config/ezplatform.yml`. Read the [cookbook recipe to learn more about it](../cookbook/importing_settings_from_a_bundle.md). -# Register Field Type +## Register Field Type -## Introduction +This section explains how to register a custom Field Type in eZ Platform. -This document explains how to register a custom Field Type in eZ Platform. It will not contain the development part as it is already covered [in the API section](../api/Field_Type_API_and_best_practices.md). - -Please be sure you first have read the [basic documentation on how to develop a custom Field Type](../api/Field_Type_API_and_best_practices.md). - -## Service container configuration +### Service container configuration To be able to declare a FieldType, you need to have [registered a bundle in your application kernel](http://symfony.com/doc/master/book/page_creation.html#the-bundle-system). This bundle needs to expose some configuration for the service container somehow (read [related Symfony documentation](http://symfony.com/doc/master/book/service_container.html#importing-other-container-configuration-resources)) -## Basic configuration +#### Basic configuration -This part relates to the [base FieldType class that interacts with the Publish API](../api/Field_Type_API_and_best_practices.md#PublicAPI). +This part relates to the [base FieldType class that interacts with the Publish API](#public-api). Let's take a basic example from `ezstring` configuration. -``` +``` yaml parameters: ezpublish.fieldType.ezstring.class: eZ\Publish\Core\FieldType\TextLine\Type   @@ -587,17 +569,17 @@ Tagging your field type service with **`ezpublish.fieldType`** is mandatory to b Basic field types configuration is located in [EzPublishCoreBundle/Resources/config/fieldtypes.yml](https://github.com/ezsystems/ezpublish-kernel/blob/master/eZ/Bundle/EzPublishCoreBundle/Resources/config/fieldtypes.yml). -## Legacy Storage Engine +#### Legacy Storage Engine -## Converter +##### Converter -As stated in [Field Type API & best practices](../api/Field_Type_API_and_best_practices.md#Legacy-storage-conversion), a conversion of Field Type values is needed in order to properly store the data into the *old* database schema (aka *Legacy Storage*). +As stated [above](#legacy-storage-conversion), a conversion of Field Type values is needed in order to properly store the data into the *old* database schema (aka *Legacy Storage*). Those converters also need to be correctly exposed as services. **Field Type converter for ezstring** -``` +``` yaml parameters: ezpublish.fieldType.ezstring.converter.class: eZ\Publish\Core\Persistence\Legacy\Content\FieldValue\Converter\TextLine   @@ -620,15 +602,15 @@ As for the tag attributes: The converter configuration for basic field types are located in [eZ/Publish/Core/settings/fieldtype\_external\_storages.yml](https://github.com/ezsystems/ezpublish-kernel/blob/master/eZ/Publish/Core/settings/fieldtype_external_storages.yml). -## External storage +##### External storage -A Field Type has the [ability to store its value (or part of it) in external data sources](Field_Type_API_and_best_practices.md#Storing-external-data). This is made possible through the `eZ\Publish\SPI\FieldType\FieldStorage` interface. Thus, if one wants to use this functionality, he needs to define a service implementing this interface and tagged as **`ezpublish.fieldType.externalStorageHandler`** to be recognized by the Repository. +A Field Type has the [ability to store its value (or part of it) in external data sources](#storing-external-data). This is made possible through the `eZ\Publish\SPI\FieldType\FieldStorage` interface. Thus, if one wants to use this functionality, he needs to define a service implementing this interface and tagged as **`ezpublish.fieldType.externalStorageHandler`** to be recognized by the Repository. Here is an example for **ezurl** field type: **External storage handler for ezurl** -``` +``` yaml parameters: ezpublish.fieldType.ezurl.externalStorage.class: eZ\Publish\Core\FieldType\Url\UrlStorage   @@ -639,17 +621,17 @@ services: - {name: ezpublish.fieldType.externalStorageHandler, alias: ezurl} ``` -The configuration is straight forward. Nothing specific except the **`ezpublish.fieldType.externalStorageHandler `**tag, the `alias` attribute still begin the *fieldTypeIdentifier*. +The configuration is straight forward. Nothing specific except the **`ezpublish.fieldType.externalStorageHandler `** tag, the `alias` attribute still begin the *fieldTypeIdentifier*. External storage configuration for basic field types is located in [EzPublishCoreBundle/Resources/config/fieldtypes.yml](https://github.com/ezsystems/ezp-next/blob/master/eZ/Bundle/EzPublishCoreBundle/Resources/config/fieldtypes.yml). -## Gateway based storage +##### Gateway based storage -As stated in the [Field Type best practices](Field-Type-API-and-best-practices_31430767.html#FieldTypeAPIandbestpractices-GatewaybasedStorage), in order to be storage agnostic and external storage handler should use a *storage gateway*. This can be done by implementing another service implementing `eZ\Publish\Core\FieldType\StorageGateway` and being tagged as `ezpublish.fieldType.externalStorageHandler.gateway`. +As stated in the [Field Type best practices](#gateway-based-storage), in order to be storage agnostic and external storage handler should use a *storage gateway*. This can be done by implementing another service implementing `eZ\Publish\Core\FieldType\StorageGateway` and being tagged as `ezpublish.fieldType.externalStorageHandler.gateway`. **Storage gateway for ezurl** -``` +``` yaml parameters: ezpublish.fieldType.ezurl.storage_gateway.class: eZ\Publish\Core\FieldType\Url\UrlStorage\Gateway\LegacyStorage   @@ -671,19 +653,17 @@ Also note that there can be several gateways per field type (one per storage eng The gateway configuration for basic field types are located in [EzPublishCoreBundle/Resources/config/storage\_engines.yml](https://github.com/ezsystems/ezpublish-kernel/blob/master/eZ/Bundle/EzPublishCoreBundle/Resources/config/storage_engines.yml). - - ## Settings schema and allowed validators - -## Internal Field Type conventions and best practices +### Internal Field Type conventions and best practices FieldType->$settingsSchema and FieldType->$allowedValidators are intentionally left free-form, to give broadest freedom to Field Type developers. However, for internal Field Types (aka those delivered with eZ Platform), a common standard should be established as best practice. The purpose of this page is to collect and unify this standard. -## Settings schema +#### Settings schema The general format of the settings schema of a Field Type is a hashmap of setting names, assigned to their type and default value, e.g.: +``` array( 'myFancySetting' => array( 'type' => 'int', @@ -694,6 +674,7 @@ The general format of the settings schema of a Field Type is a hashmap of settin 'default' => 'Sindelfingen', ), ); +``` The type should be either a valid PHP type shortcut (TB discussed) or one of the following special types: @@ -701,9 +682,7 @@ The type should be either a valid PHP type shortcut (TB discussed) or one of the - Choice (an enumeration) - <<<YOUR TYPE HERE>>> -  - -## Validators +#### Validators Validators are internally handled through a special ValidatorService … (TBD: Explain service and how it works) diff --git a/docs/api/general_rest_usage.md b/docs/api/general_rest_usage.md index 2950d8839a..1a8ed37a25 100644 --- a/docs/api/general_rest_usage.md +++ b/docs/api/general_rest_usage.md @@ -1,9 +1,7 @@ - - # General REST usage -As explained in the [introduction](../api/rest_api_guide.md), the REST API is based on a very limited list of general principles: +As explained in the [introduction](rest_api_guide.md), the REST API is based on a very limited list of general principles: - each resource (uri) interacts with a part of the system (Content, URL aliases, User Groups, etc.), - for each resource, one or more verbs are available, each having a different effect (delete a Content item, get a URL Alias, list user groups, etc.), @@ -11,11 +9,11 @@ As explained in the [introduction](../api/rest_api_guide.md), the REST API is ba ## Anatomy of a REST call -## What we can learn from a GET request +### What we can learn from a GET request This verb is used to query the API for information. It is one of the two operations web browsers implement, and the one most commonly used. -## Request +### Request The only requirement for this verb is usually the resource URI, and the accept header. On top of that, cache request headers can be added, like `If-None-Match`, but those aren't fully implemented yet in eZ Publish 5.0. @@ -45,17 +43,17 @@ Content-Length: xxx The length of our content, provided by the Content-Length header, isn't *that* useful. -## HTTP Code +###### HTTP Code The API responded here with a standard 200 OK HTTP response code, which is the expected response code for a "normal" GET request. Some GET requests, like [getting a Content item's current version](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#13241%C2%A0%C2%A0%C2%A0get-current-version), may reply with a 301 Moved permanently, or 307 Temporary redirect code. Errors will be indicated with HTTP error codes, like 404 for Not Found, or 500 for Internal server error. The [REST specifications](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst) provide the list of every HTTP response code you can expect from implemented resources. -## Content-Type header +###### Content-Type header As long as a response contains an actual HTTP body, the Content-Type header will be used to specify which Content-Type is contained in the response. In that case, a ContentInfo (`Content-Type: application/vnd.ez.api.ContentInfo`) in XML (`Content-Type: application/vnd.ez.api.ContentInfo+xml`) -## Accept-Patch header +###### Accept-Patch header This is a very interesting one. @@ -65,17 +63,17 @@ This last part means that if we send a PATCH /content/objects/23 request with a REST will use the `Accept-Patch` header to indicate how to **modify** the returned **data**. -## Other headers: Location +###### Other headers: Location Depending on the resource, request & response headers will vary. For instance, [creating content](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#13231%C2%A0%C2%A0%C2%A0creating-content), or [getting a Content item's current version](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#13241%C2%A0%C2%A0%C2%A0get-current-version) will both send a `Location` header to provide you with the requested resource's ID. Those particular headers generally match a specific list of HTTP response codes. Location is sent by `201 Created`, `301 Moved permanently,` `307 Temporary redirect responses`. This list isn't finished, but you can expect those HTTP responses to provide you with a Location header. -## Other headers: Destination +###### Other headers: Destination This request header is the request counterpart of the Location response header. It is used in a COPY / MOVE operation, like [copying a Content item](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#13236%C2%A0%C2%A0%C2%A0copy-content), on a resource to indicate where the resource should be moved to, using the ID of the destination. -## Response body +#### Response body **Load ContentInfo response body**  Expand source @@ -105,7 +103,7 @@ As explained above, the API has told us that we could modify content object 23 b The REST API data structs mostly match a PHP Public API value object -## Value objects representation +#### Value objects representation Value objects like [ContentInfo](https://github.com/ezsystems/ezp-next/blob/master/eZ/Publish/API/Repository/Values/Content/ContentInfo.php) basically feature two types of fields: basic, local fields (modified, name...) and foreign field(s) references (sectionId, mainLocationId). @@ -167,11 +165,7 @@ Accept: application/vnd.ez.api.Root+json X-Siteaccess: ezdemo_site_admin ``` -  - - - -# REST API Authentication +## REST API Authentication The REST API supports two authentication methods: session, and basic.  @@ -181,13 +175,13 @@ The REST API supports two authentication methods: session, and basic.  Session-based is the default authentication method, as this is needed for UI. -## Session based authentication +### Session based authentication This authentication method requires a Session cookie to be sent with each request. If this authentication method is used with a web browser, this session cookie is automatically available as soon as your visitor logs in. Add it as a cookie to your REST requests, and the user will be authenticated. -### Logging in +#### Logging in It is also possible to create a session for the visitor if they aren't logged in yet. This is done by sending a **`POST`** request to `/user/sessions`. Logging out is done using a **`DELETE`** request on the same resource. @@ -195,7 +189,7 @@ More information [Session-based authentication chapter of the REST specifications](https://github.com/ezsystems/ezp-next/blob/master/doc/specifications/rest/REST-API-V2.rst#123%C2%A0%C2%A0%C2%A0session-based-authentication) -## HTTP Basic authentication +### HTTP Basic authentication To enable HTTP Basic authentication, you need to edit app`/config/security.yml`, and add/uncomment the following block. Note that this is enabled by default. @@ -222,46 +216,46 @@ Accept: application/vnd.ez.api.Root+json Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== ``` -## Error handling +### Error handling Error handling in the REST API is fully based on HTTP error codes. As a web developer, you are probably familiar with the most common ones: 401 Unauthorized, 404 Not Found or 500 Internal Server Error. The REST API uses those, along with a few more, to allow proper error handling. The complete list of error codes used and the conditions in which they apply are specified in the [reference documentation](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst). -## General error codes +### General error codes A few error codes apply to most resources (if they *are* applicable) -### 500 Internal Server Error +#### 500 Internal Server Error The server encountered an unexpected condition, usually an exception, which prevented it from fulfilling the request: database down, permissions or configuration error. -### 501 Not Implemented +#### 501 Not Implemented Returned when the requested method has not yet been implemented. As of eZ Publish 5.0, most of User, User group, Content, Location and Content Type have been implemented. Some of their methods, as well as other features, may return a 501. -### 404 Not Found +#### 404 Not Found Returned when the request failed because the request object was not found. You should be familiar with this one. -### 405 Method Not Allowed +#### 405 Method Not Allowed Returned when the requested REST API resource doesn't support the HTTP verb that was used. -### 406 Not Acceptable +#### 406 Not Acceptable Returned when an accept header sent with the requested isn't supported. -## Error handling in your REST implementation +### Error handling in your REST implementation It is up to you, in your client implementation, to handle those codes by checking if an error code (4xx or 5xx) was returned instead of the expected 2xx or 3xx. -## REST API Countries list +### REST API Countries list Countries list is a REST service that gives access to an [ISO-3166](http://en.wikipedia.org/wiki/ISO_3166) formatted list of world countries. It is useful when presenting a country options list from any application. -## Get the list of countries +### Get the list of countries To send a GET request to the REST API Countries list, you have to provide the Content Type header `application/vnd.ez.api.CountriesList+xml`. @@ -273,11 +267,7 @@ Method: GET Content-Type: application/vnd.ez.api.CountriesList+xml ``` -See the [General REST usage documentation page](General-REST-usage_31430291.html) for further information.[](https://gist.github.com/bdunogier/8665017#example) - -### Usage example - -  +#### Usage example **Countries list request** @@ -287,8 +277,6 @@ Host: example.com Accept: application/vnd.ez.api.CountriesList+xml ``` -  - The HTTP response will it be with a 200 OK Header. **Countries list response headers** @@ -298,8 +286,6 @@ HTTP/1.1 200 Content-Type: application/vnd.ez.api.CountriesList+xml ``` -  - And the body of the Response is XML formatted country list with names and codes according to the ISO-3166 standard.  ISO-3166 diff --git a/docs/api/js_client.md b/docs/api/js_client.md index 3bbda6c7ca..0871ac0a91 100644 --- a/docs/api/js_client.md +++ b/docs/api/js_client.md @@ -1,11 +1,9 @@ - - # JS Client The JavaScript REST API Client is a JavaScript library meant to ease the use of the eZ Platform REST API. For now, it can only be used in a web browser. -See [Using the JavaScript REST API Client](Using-the-JavaScript-REST-API-Client_31430299.html) for a guide on how to use the client, and view the [generated JS API Client reference](http://ezsystems.github.io/javascript-rest-client/). +See [below](#using-the-javascript-rest-api-client) for a guide on how to use the client, and view the [generated JS API Client reference](http://ezsystems.github.io/javascript-rest-client/). ## Using the JavaScript REST API Client @@ -15,7 +13,7 @@ The JavaScript REST API Client is a JavaScript library meant to ease the use of ## Installation -## In the PlatformUIAssetsBundle +### In the PlatformUIAssetsBundle Since the JavaScript REST Client is one of the foundations of [the Platform Backend Interface](../guide/extending_ez_platform_ui.md), the client is provided by the [PlatformUIAssetsBundle](https://github.com/ezsystems/PlatformUIAssetsBundle) which is installed by default. As a result, the client is directly available and can be embedded in any Platform-generated page with the following Twig code: @@ -27,7 +25,7 @@ Since the JavaScript REST Client is one of the foundations of [the Platform Back ``` -## With Bower +### With Bower Alternatively, the JavaScript REST Client can be installed directly in any project with [Bower](http://bower.io/): @@ -45,7 +43,7 @@ It is also possible to directly retrieve either `dist/CAPI.js` or `dist/CAPI-min ## Usage examples -Once included, `CAPI.js` exports the `eZ` namespace which contains `eZ.CAPI`, the constructor function of the client. This constructor must receive the API end point and an authentication agent responsible for handling the authentication (session or basic auth). This is detailed in the [Instantiation and authentication](http://doc.ez.no#UsingtheJavaScriptRESTAPIClient-Instantiationandauthentication) section below. +Once included, `CAPI.js` exports the `eZ` namespace which contains `eZ.CAPI`, the constructor function of the client. This constructor must receive the API end point and an authentication agent responsible for handling the authentication (session or basic auth). This is detailed in the [Instantiation and authentication](#instantiation-and-authentication) section below. [The auto-generated API documentation of the JavaScript REST API client is available online.](http://ezsystems.github.io/javascript-rest-client) Like in the Public API, the code is organized around 3 main services: @@ -58,16 +56,16 @@ In essence, the operations available through those services are asynchronous, so 1. `error`: depending on the success of the operation, this parameter is either `false` or a [`CAPIError`](http://ezsystems.github.io/javascript-rest-client/classes/CAPIError.html) instance representing the error 2. `response`: it's always of a [`Response`](http://ezsystems.github.io/javascript-rest-client/classes/Response.html) instance allowing you to retrieve any information from the REST API response -## Instantiation and authentication +### Instantiation and authentication [The `eZ.CAPI` constructor function](http://ezsystems.github.io/javascript-rest-client/classes/CAPI.html) expects two parameters: 1. the API end point URI -2. an authentication agent instance to configure the client for [the authentication mechanism configuration in eZ Platform](../general_rest_usage.md#REST-API-Authentication). +2. an authentication agent instance to configure the client for [the authentication mechanism configuration in eZ Platform](general_rest_usage.md#rest-api-authentication). The JavaScript REST Client comes with two authentication agents for the Session and Basic Auth authentication mechanism. -## Session auth +#### Session auth The Session Auth Agent expects an object describing the existing Session or containing the credentials for the user to create the corresponding session. So if the user is not yet authenticated, the client can be instantiated with: @@ -121,7 +119,7 @@ capi.isLoggedIn(function (error, response) { }); ``` -## Basic auth +#### Basic auth When configured in the Basic Authentication, the basic auth agent just expects the user's credentials: @@ -147,7 +145,7 @@ capi.logIn(function (error, response) { }); ``` -## Loading a ContentInfo or a Content +### Loading a ContentInfo or a Content To load a ContentInfo, you need [the Content Service](http://ezsystems.github.io/javascript-rest-client/classes/ContentService.html), it is returned by the `getContentService` method on the client instance: @@ -178,7 +176,7 @@ contentService.loadContentInfo(contentRestId, function (error, response) { If you run this example, you should see in the browser network panel a GET HTTP request to with the necessary headers to get a JSON representation of the ContentInfo. If you want to load the Content instead, you can use [the `loadContent` method](http://ezsystems.github.io/javascript-rest-client/classes/ContentService.html#method_loadContent). -## Moving a Location +### Moving a Location To move a Location, [the Content Service](http://ezsystems.github.io/javascript-rest-client/classes/ContentService.html) is also needed, this operation will generate a MOVE HTTP request. If configured for the session authentication mechanism, the client will automatically add the CSRF Token. @@ -207,9 +205,9 @@ contentService.moveSubtree(locationRestId, newParentLocationRestId, function (er }) ``` -## Searching for Content or Location +### Searching for Content or Location -Searching for Content or Location can be done with [REST views](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#views). REST views can be configured with the [search engine criteria](../guide/search_criteria_reference.md) to match some Content items or Locations: +Searching for Content or Location can be done with [REST views](https://github.com/ezsystems/ezpublish-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst#views). REST views can be configured with the [search engine criteria](../guide/search.md#search-criteria-reference) to match some Content items or Locations: **REST views** @@ -240,7 +238,7 @@ contentService.createView(query, function (error, response) { }) ``` -REST views +!!! note "REST views" -REST views are designed to be persisted but this feature is not yet implemented. As a result, when calling `createView`, the POST request does not create the view but directly returns the results. + REST views are designed to be persisted but this feature is not yet implemented. As a result, when calling `createView`, the POST request does not create the view but directly returns the results.   diff --git a/docs/api/public_php_api.md b/docs/api/public_php_api.md index 178aec2c33..557530e570 100644 --- a/docs/api/public_php_api.md +++ b/docs/api/public_php_api.md @@ -1,8 +1,5 @@ - - # eZ Platform Public PHP API - The PHP API is also commonly referred to as the "*Public API*". Currently it exposes a Repository which allows you to create, read, update, manage and delete all objects available in eZ Platform, first and foremost content, but also related objects like Sections, Locations, Content Types, Content Type groups, languages and so on. ### eZ Platform API Repository @@ -18,23 +15,23 @@ It will allow you to create, retrieve, update and delete all the eZ Platform obj $repository = $container->get( 'ezpublish.api.repository' ); ``` - By itself, the repository doesn't do much. It allows three types of operations: user authentication (getting / changing the current user), issuing transactions, and obtaining services.  +By itself, the repository doesn't do much. It allows three types of operations: user authentication (getting / changing the current user), issuing transactions, and obtaining services.  -Inline objects documentation +!!! tip "Inline objects documentation" -Pay attention to the inline phpdoc block in this code stub. It tells your IDE that `$repository` is an instance of  ` \eZ\Publish\API\Repository\Repository `. If your IDE supports this feature, you will get code completion on the `$repository` object. This helper is a huge time saver when it comes to learning about the eZ Platform API. + Pay attention to the inline phpdoc block in this code stub. It tells your IDE that `$repository` is an instance of  `\eZ\Publish\API\Repository\Repository`. If your IDE supports this feature, you will get code completion on the `$repository` object. This helper is a huge time saver when it comes to learning about the eZ Platform API. ### The service container The above code snippet implies that the [service container](http://symfony.com/doc/2.0/book/service_container.html) is available in the context you are writing your code in. -In controllers, this generally is done by extending the Symfony ` Controller ` class. It comes with a ` get() ` method that calls the service container. In command line scripts, it requires that you extend the [`ContainerAwareCommand`](http://api.symfony.com/2.1/Symfony/Bundle/FrameworkBundle/Command/ContainerAwareCommand.html) base class instead of `Controller`. This class provides you with a `getContainer()` method that returns the service container. +In controllers, this generally is done by extending the Symfony `Controller` class. It comes with a `get()` method that calls the service container. In command line scripts, it requires that you extend the [`ContainerAwareCommand`](http://api.symfony.com/2.1/Symfony/Bundle/FrameworkBundle/Command/ContainerAwareCommand.html) base class instead of `Controller`. This class provides you with a `getContainer()` method that returns the service container. -Getting the repository from eZ Platform controllers +!!! note "Getting the repository from eZ Platform controllers" -In order to make it even easier to obtain the repository from controllers code, eZ Platform controllers extend a custom  [Controller](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Bundle/EzPublishCoreBundle/Controller.html) class that provides a [`getRepository()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Bundle/EzPublishCoreBundle/Controller.html#method_getRepository) method which directly returns the repository from the service container. + In order to make it even easier to obtain the repository from controllers code, eZ Platform controllers extend a custom  [Controller](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Bundle/EzPublishCoreBundle/Controller.html) class that provides a [`getRepository()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Bundle/EzPublishCoreBundle/Controller.html#method_getRepository) method which directly returns the repository from the service container. -You can and should of course do the same in your custom controllers. + You can and should of course do the same in your custom controllers. ### Authentication @@ -44,7 +41,7 @@ Logging in to the Repository is covered in other recipes of the Cookbook. ### Services -The main entry point to the repository's features are services. The Public API breaks down access to Content, User, Content Types and other features into various services. Those services are obtained via the [Repository](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Repository.html), using `get`\[ServiceName\]`()` methods: ` getContentService() `, ` getUserService() `, etc. +The main entry point to the repository's features are services. The Public API breaks down access to Content, User, Content Types and other features into various services. Those services are obtained via the [Repository](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Repository.html), using `get`\[ServiceName\]`()` methods: `getContentService()`, `getUserService()`, etc. Throughout the Cookbook, you will be guided through the various capabilities those services have, and how you can use them to implement your projects. @@ -66,23 +63,19 @@ In order to update or create elements in the Repository, you will use structs. T Using them is also covered in the Cookbook. - - -# Public API Guide - +## Public API Guide The public API will give you an easy access to the eZ Platform content repository. This repository is the core component that manages content, Locations, Sections, Content Types, Users, User groups, and Roles. It also provides a new, clear interface for plugging in custom Field Types. -  The public API is built on top of a layered architecture, including a persistence API that abstracts storage. By using the public API, you are sure that your code will be forward compatible with future releases based on enhanced, scalable and high-performance storage engines. Applications based on the public API are also fully backwards compatible by using the included storage engine based on the current kernel and database model. -## About this Guide +### About this Guide The objective of this Public API Guide is to progressively lead you through useful, everyday business logic, using the API in concrete recipes: obtaining a Location from a Content item, fetching a set of Content items, creating a User, and so on. For each recipe, newly introduced elements will be explained in detail, including the required API components (services, value objects, etc.).  -### Suggested tools +#### Suggested tools In addition to this cookbook, we strongly recommend that you use a full featured PHP IDE, such as Eclipse or PHPStorm. It will provide you information on every piece of code you use, including objects and classes documentation. We have paid very careful attention to PHPDoc throughout this API, and such a tool is a very valuable help when using this API. @@ -91,12 +84,217 @@ On top of this, generated public API documentation can be found online, in vario - doxygen: - sami: +## Getting started with the Public API + +In this chapter, we will see two ways of customizing eZ Platform: command line scripts (for import scripts, for instance), and custom controllers. + +### Symfony bundle + +In order to test and use Public API code, you will need to build a custom bundle. Bundles are Symfony's extensions, and are therefore also used to extend eZ Platform. Symfony 2 provides code generation tools that will let you create your own bundle and get started in a few minutes. + +In this chapter, we will show how to create a custom bundle, and implement both a command line script and a custom route with its own controller action and view. All shell commands assume that you use some Linux shell, but those commands would of course also work on Windows systems. + +#### Generating a new bundle + +First, change the directory to your eZ Platform root. + +``` bash +$ cd /path/to/ezplatform +``` + +Then use the app/console application with the `generate:bundle` command to start the bundle generation wizard. + +Let's follow the instructions provided by the wizard. Our objective is to create a bundle named `EzSystems/Bundles/CookBookBundle`, located in the `src` directory. + +``` bash +$ php app/console generate:bundle +``` + +The wizard will first ask about our bundle's namespace. Each bundle's namespace should feature a vendor name (in our own case: `EzSystems`), optionally followed by a sub-namespace (we could have chosen to use `Bundle`), and end with the actual bundle's name, suffixed with Bundle: `CookbookBundle`. + +**Bundle namespace** + +``` +Your application code must be written in bundles. This command helps you generate them easily. + +Each bundle is hosted under a namespace (like Acme/Bundle/BlogBundle). + +The namespace should begin with a "vendor" name like your company name, your project name, or your client name, followed by one or more optional category sub-namespaces, and it should end with the bundle name itself (which must have Bundle as a suffix). + +See http://symfony.com/doc/current/cookbook/bundles/best_practices.html#index-1 for more details on bundle naming conventions. + +Use / instead of \ for the namespace delimiter to avoid any problem. + +Bundle namespace: EzSystems/CookbookBundle +``` + +You will then be asked about the Bundle's name, used to reference your bundle in your code. We can go with the default, `EzSystemsCookbookBundle`. Just hit Enter to accept the default. + +**Bundle name** + +``` +In your code, a bundle is often referenced by its name. It can be the concatenation of all namespace parts but it's really up to you to come up with a unique name (a good practice is to start with the vendor name). + +Based on the namespace, we suggest EzSystemsCookbookBundle. + +Bundle name [EzSystemsCookbookBundle]: +``` + +The next question is your bundle's location. By default, the script offers to place it in the `src` folder. This is perfectly acceptable unless you have a good reason to place it somewhere else. Just hit Enter to accept the default. + +**Bundle directory** + +``` +The bundle can be generated anywhere. The suggested default directory uses the standard conventions. + + +Target directory [/path/to/ezpublish5/src]: +``` + +Next, you need to choose the generated configuration's format, out of YAML, XML, PHP or annotations. We mostly use yaml in eZ Platform, and we will use it in this cookbook. Enter 'yml', and hit Enter. + +**Configuration format** + +``` +Determine the format to use for the generated configuration. + +Configuration format (yml, xml, php, or annotation) [annotation]: yml +``` + +The last choice is to generate code snippets demonstrating the Symfony directory structure. If you're learning Symfony, it is a good idea to accept, as it will create a controller, yaml files, etc. + +**Generate snippets & directory structure** + +``` +To help you get started faster, the command can generate some code snippets for you. + +Do you want to generate the whole directory structure [no]? yes +``` + +The generator will then summarize the previous choices, and ask for confirmation. Hit Enter to confirm. + +**Summary and confirmation** + +``` +You are going to generate a "EzSystems\Bundle\CookbookBundle\EzSystemsCookbookBundle" bundle in "/path/to/ezpublish5/src/" using the "yml" format. + +Do you confirm generation [yes]? yes +``` + +The wizard will generate the bundle, check autoloading, and ask about the activation of your bundle. Hit Enter in the answer to both questions to have your bundle automatically added to your Kernel (`app/AppKernel.php`) and routes from your bundle added to the existing routes (`app/config/routing.yml`). + +**Activation and generation** + +``` + Bundle generation + +Generating the bundle code: OK +Checking that the bundle is autoloaded: OK +Confirm automatic update of your Kernel [yes]? +Enabling the bundle inside the Kernel: OK +Confirm automatic update of the Routing [yes]? +Importing the bundle routing resource: OK + + You can now start using the generated code! +  +``` + +Your bundle should be generated and activated. Let's now see how you can interact with the Public API by creating a command line script, and a custom controller route and action. + +#### Creating a command line script in your bundle + +Writing a command line script with Symfony 2 is *very* easy. The framework and its bundles ship with a few scripts. They are all started using `php app/console `. You can get the complete list of existing command line scripts by executing `php app/console list` from the eZ Platform root. + +In this chapter, we will create a new command, identified as `ezpublish:cookbook:hello`, that takes an optional name argument, and greets that name. To do so, we need one thing: a class with a name ending with "Command" that extends `Symfony\Component\Console\Command\Command`. Note that in our case, we use `ContainerAwareCommand` instead of `Command`, since we need the dependency injection container to interact with the Public API. In your bundle's directory (`src/EzSystems/CookbookBundle`), create a new directory named `Command`, and in this directory, a new file named `HelloCommand.php`. + +Add this code to the file: + +**HelloCommand.php** + +``` php +. +This is the skeleton for a command line script. + +One class with a name ending with "Command" (`HelloCommand`), extends `Symfony\Bundle\FrameworkBundle\Command\Command`, and is part of our bundle's Command namespace. It has two methods: `configure()`, and `execute()`. We also import several classes & interfaces with the use keyword. The first two, `InputInterface` and `OutputInterface` are used to 'typehint' the objects that will allow us to provide input & output management in our script. + +`Configure` will be used to set your command's name, as well as its options and arguments. `Execute` will contain the actual implementation of your command. Let's start by creating the `configure()` method. + +**TestCommand::configure()** + +``` php +protected function configure() +{ + $this->setName( 'ezpublish:cookbook:hello' ); + $this->setDefinition( + array( + new InputArgument( 'name', InputArgument::OPTIONAL, 'An argument' ) + ) + ); +} +``` + +First, we use `setName()` to set our command's name to "`ezpublish:cookbook:hello`". We then use `setDefinition()` to add an argument, named `name`, to our command. + +You can read more about argument definitions and further options in the [Symfony 2 Console documentation](http://symfony.com/doc/2.0/components/console/introduction.html). Once this is done, if you run `php app/console list`, you should see `ezpublish:cookbook:hello` listed in the available commands. If you run it, it will however still do nothing. + +Let's just add something very simple to our `execute()` method so that our command actually does something. + +**TestCommand::execute()** + +``` php +protected function execute( InputInterface $input, OutputInterface $output ) +{ + // fetch the input argument + if ( !$name = $input->getArgument( 'name' ) ) + { + $name = "World"; + } + $output->writeln( "Hello $name" ); +} +``` + +You can now run the command from the eZ Platform root. + +**Hello world** + +``` brush: +$ php app/console ezpublish:cookbook:hello world +Hello world +``` + +#### Creating a custom route with a controller action + +In this short chapter, we will see how to create a new route that will catch a custom URL and execute a controller action. We want to create a new route, `/cookbook/test`, that displays a simple 'Hello world' message. This tutorial is a simplified version of the official one that can be found on . During our bundle's generation, we have chosen to generate the bundle with default code snippets. Fortunately, almost everything we need is part of those snippets. We just need to do some editing, in particular in two locations: `src/EzSystems/Resources/CookbookBundle/config/routing.yml` and `src/EzSystems/CookbookBundle/Controllers/DefaultController.php`. The first one will be used to configure our route (`/cookbook/test`) as well as the controller action the route should execute, while the latter will contain the actual action's code. -#### routing.yml +##### routing.yml This is the file where we define our action's URL matching. The generated file contains this YAML block: @@ -120,7 +318,7 @@ ezsystems_cookbook_hello: We define a route that matches the URI /cookbook/\* and executes the action `hello` in the Default controller of our bundle. The next step is to create this method in the controller. -#### DefaultController.php +##### DefaultController.php This controller was generated by the bundle generator. It contains one method, `helloAction()`, that matched the YAML configuration we have changed in the previous part. Let's just rename the `indexAction()` method so that we end up with this code. @@ -152,17 +350,13 @@ For convenience, a custom controller is available at [eZ\\Bundle\\EzPublishCoreB You are encouraged to use it for your custom controllers that interact with eZ Platform. -  - With both command line scripts and HTTP routes, you have the basics you need to start writing Public API code. - -# Browsing, finding, viewing - +## Browsing, finding, viewing We will start by going through the various ways to find and retrieve content from eZ Platform using the API. While this will be covered in further dedicated documentation, it is necessary to explain a few basic concepts of the Public API. In the following recipes, you will learn about the general principles of the API as they are introduced in individual recipes. -## Displaying values from a Content item +### Displaying values from a Content item In this recipe, we will see how to fetch a Content item from the repository, and obtain its Field's content.  @@ -224,7 +418,7 @@ try Everything starting from line 5 is about getting our Content and iterating over its Fields. You can see that the whole logic is part of a `try/catch` block. Since the Public API uses Exceptions for error handling, this is strongly encouraged, as it will allow you to conditionally catch the various errors that may happen. We will cover the exceptions we expect in a later paragraph. -The first thing we do is use the Content Service to load a Content item using its ID, 66: `$contentService->loadContent ` `( 66 )`. As you can see on the API doc page, this method expects a Content ID, and returns a [Content Value Object](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Content.html). +The first thing we do is use the Content Service to load a Content item using its ID, 66: `$contentService->loadContent ( 66 )`. As you can see on the API doc page, this method expects a Content ID, and returns a [Content Value Object](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Content.html). ``` php foreach( $contentType->fieldDefinitions as $fieldDefinition ) @@ -286,7 +480,7 @@ As said earlier, the Public API uses [Exceptions](http://php.net/exceptions) t It is a good practice to cover each exception you expect to happen. In this case, since our Command takes the Content ID as a parameter, this ID may either not exist, or the referenced Content item may not be visible to our user. Both cases are covered with explicit error messages. -## Traversing a Location subtree +### Traversing a Location subtree This recipe will show how to traverse a Location's subtree. The full code implements a command that takes a Location ID as an argument and recursively prints this location's subtree. @@ -315,7 +509,7 @@ catch( \eZ\Publish\API\Repository\Exceptions\UnauthorizedException $e ) } ``` -As for the ContentService, `loadLocation()` returns a Value Object, here a ` Location `. Errors are handled with exceptions: ` NotFoundException ` if the Location ID couldn't be found, and ` UnauthorizedException ` if the current repository user isn't allowed to view this Location. +As for the ContentService, `loadLocation()` returns a Value Object, here a `Location`. Errors are handled with exceptions: `NotFoundException` if the Location ID couldn't be found, and `UnauthorizedException` if the current repository user isn't allowed to view this Location. **Iterating over a Location's children** @@ -335,19 +529,19 @@ private function browseLocation( Location $location, OutputInterface $output, $d Note that unlike `loadLocation()`, we don't need to care for permissions here: the currently logged-in user's permissions will be respected when loading children, and Locations that can't be viewed won't be returned at all. -Full code +!!! note "Full code" -Should you need more advanced children fetching methods, the ` SearchService ` is what you are looking for. + Should you need more advanced children fetching methods, the `SearchService` is what you are looking for. -## Viewing Content Metadata +### Viewing Content Metadata Content is a central piece in the Public API. You will often need to start from a Content item, and dig in from its metadata. Basic content metadata is made available through ` ContentInfo ` objects. This Value Object mostly provides primitive fields: `contentTypeId`, `publishedDate` or `mainLocationId`. But it is also used to request further Content-related Value Objects from various services. The full example implements an `ezpublish:cookbook:view_content_metadata` command that prints out all the available metadata, given a Content ID. -Full code +!!! note "Full code" - + We introduce here several new services: [`URLAliasService`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/URLAliasService.html), [`UserService`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/UserService.html) and [`SectionService`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/SectionService.html). The concept should be familiar to you now. @@ -363,7 +557,7 @@ $sectionService = $repository->getSectionService(); $userService = $repository->getUserService(); ``` -### Setting the Repository User +#### Setting the Repository User In a command line script, the repository runs as if executed by the anonymous user. In order to identify it as a different user, you need to use the ` UserService ` as follows (in this example `14` is the ID of the administrator user): @@ -386,7 +580,7 @@ $user = $userService->loadUserByLogin('admin'); $permissionResolver->setCurrentUserReference($user); ``` -### The ContentInfo Value Object +#### The ContentInfo Value Object We will now load a `ContentInfo` object using the provided ID and use it to get our Content item's metadata @@ -394,7 +588,7 @@ We will now load a `ContentInfo` object using the provided ID and use it to get $contentInfo = $contentService->loadContentInfo( $contentId ); ``` -### Locations +#### Locations **Getting Content Locations** @@ -409,13 +603,11 @@ foreach ( $locations as $location ) } ``` -We first use ` LocationService ::loadLocations()` to **get** the **Locations** for our `ContentInfo`. This method returns an array of [`Location`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Location.html) Value Objects. In this example, we print out the Location's path string (/path/to/content). We also use [URLAliasService::reverseLookup()](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/URLAliasService.html#method_reverseLookup) to get the Location's main [URLAlias](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/URLAlias.html). - -  +We first use `LocationService::loadLocations()` to **get** the **Locations** for our `ContentInfo`. This method returns an array of [`Location`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Location.html) Value Objects. In this example, we print out the Location's path string (/path/to/content). We also use [URLAliasService::reverseLookup()](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/URLAliasService.html#method_reverseLookup) to get the Location's main [URLAlias](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/URLAlias.html). -### Relations +#### Relations -We now want to list relations from and to our Content. Since relations are versioned, we need to feed the [`ContentService::loadRelations()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/ContentService.html#method_loadRelations) with a ` VersionInfo ` object. We can get the current version's `VersionInfo` using [`ContentService::loadVersionInfo()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/ContentService.html#method_loadVersionInfo). If we had been looking for an archived version, we could have specified the version number as the second argument to this method. +We now want to list relations from and to our Content. Since relations are versioned, we need to feed the [`ContentService::loadRelations()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/ContentService.html#method_loadRelations) with a `VersionInfo` object. We can get the current version's `VersionInfo` using [`ContentService::loadVersionInfo()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/ContentService.html#method_loadVersionInfo). If we had been looking for an archived version, we could have specified the version number as the second argument to this method. **Browsing a Content's relations** @@ -436,7 +628,7 @@ if ( !empty( $relations ) ) We can iterate over the [Relation](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Relation.html) objects array we got from `loadRelations()`, and use these Value Objects to get data about our relations. It has two main properties: `destinationContentInfo`, and `sourceContentInfo`. They also hold the relation type (embed, common, etc.), and the optional Field this relations is made with. -### ContentInfo properties +#### ContentInfo properties We can of course get our Content item's metadata by using the Value Object's properties. @@ -454,9 +646,9 @@ $output->writeln( " Main Language: $contentInfo->mainLanguageCode" $output->writeln( " Always available: " . ( $contentInfo->alwaysAvailable ? 'Yes' : 'No' ) ); ``` -### Owning user +#### Owning user -We can use [`UserService::loadUser()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/UserService.html#method_loadUser) with Content `ownerId` property of our `ContentInfo` to load the Content's owner as a ` User ` Value Object. +We can use [`UserService::loadUser()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/UserService.html#method_loadUser) with Content `ownerId` property of our `ContentInfo` to load the Content's owner as a `User` Value Object. ``` php $owner = $userService->loadUser( $contentInfo->ownerId ); @@ -465,7 +657,7 @@ $output->writeln( " Owner: " . $owner->contentInfo->name ); To get the current version's creator, and not the content's owner, you need to use the `creatorId` property from the current version's `VersionInfo` object. -### Section +#### Section The Section's ID can be found in the `sectionId` property of the `ContentInfo` object. To get the matching Section Value Object, you need to use the `SectionService::loadSection()` method. @@ -474,9 +666,9 @@ $section = $sectionService->loadSection( $contentInfo->sectionId ); $output->writeln( " Section: $section->name" ); ``` -### Versions +#### Versions -To conclude we can also iterate over the Content's version, as ` VersionInfo ` Value Objects. +To conclude we can also iterate over the Content's version, as `VersionInfo` Value Objects. ``` php $versionInfoArray = $contentService->loadVersions( $contentInfo ); @@ -493,9 +685,9 @@ if ( !empty( $versionInfoArray ) ) } ``` -We use the ` ContentService::loadVersions() ` method and get an array of `VersionInfo` objects. +We use the `ContentService::loadVersions()` method and get an array of `VersionInfo` objects. -#### Version statuses +##### Version statuses V1.11 @@ -512,7 +704,7 @@ The new methods also enable you to use the following in Twig templates: - `version.archived` -## Search +### Search In this section we will cover how the [`SearchService`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/SearchService.html) can be used to search for Content, by using a [`Query`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Query.html) and a combinations of [`Criteria`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Query/Criterion.html) you will get a [`SearchResult`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Search/SearchResult.html) object back containing list of Content and count of total hits. In the future this object will also include facets, spell checking and "more like this" when running on a backend that supports it *(for instance Solr)*. @@ -523,7 +715,7 @@ Query object contains two properties you can set criteria on, `filter` and `quer - `query:` Has an effect on scoring *(relevancy)* calculation, and thus also on the default sorting if no `sortClause` is specified, *when used with Solr and Elastic.* - Typically you'll use this for `FullText` search criterion, and otherwise place everything else on `filter`. -### Performing a simple full text search +#### Performing a simple full text search Full code @@ -531,7 +723,7 @@ Full code In this recipe, we will run a simple full text search over every compatible attribute. -#### Query and Criterion objects +##### Query and Criterion objects We introduce here a new object: `Query`. It is used to build up a Content query based on a set of `Criterion` objects. @@ -551,7 +743,7 @@ The full list of criteria can be found on your installation in the following dir   -#### Running the search query and using the results +##### Running the search query and using the results The `Query` object is given as an argument to [`SearchService::findContent()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/SearchService.html#method_findContent). This method returns a `SearchResult` object. This object provides you with various information about the search operation (number of results, time taken, spelling suggestions, or facets, as well as, of course, the results themselves. @@ -572,7 +764,7 @@ Tip   -### Retrieving Sort Clauses for parent location +#### Retrieving Sort Clauses for parent location V1.7.0 @@ -580,7 +772,7 @@ You can use the method $parentL`ocation->getSortClauses()` to return an array of   -### Performing an advanced search +#### Performing an advanced search Full code @@ -606,15 +798,15 @@ $result = $searchService->findContent( $query ); A [`Subtree`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Query/Criterion/Subtree.html) criterion limits the search to the subtree with pathString, which looks like: `/1/2/`. A [`ContentTypeId`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Query/Criterion/ContentTypeId.html) Criterion to limit the search to Content of Content Type 1. Those two criteria are grouped with a `LogicalAnd` operator. The query is executed as before, with `SearchService::findContent()`. -#### Fine-tuning search results +##### Fine-tuning search results -##### `$languageFilter` +###### `$languageFilter` The `$languageFilter` parameter provides a prioritized list of languages for the current SiteAccess. Passing it is recommended for front-end use, because otherwise all languages of the Content items will be returned. Additionally, you can make use of the `useAlwaysAvailable` argument of the $`languageFilter`. This in turn uses the `alwaysAvailable` flag whose default is set on Content Type. When it is set to `true`, it ensures that when a language from the prioritized list can't be matched, the Content will be returned in its main language. -##### `Criterion\Visibility` +###### `Criterion\Visibility` `Criterion\Visibility` enables you to ensure that only visible content will be returned. @@ -634,7 +826,7 @@ $searchService->findLocations($query, ['languages' => $configResolver->getParameter('languages')]); ``` -### Performing a fetch like search +#### Performing a fetch like search Full code @@ -666,13 +858,11 @@ $query->filter = new Criterion\LogicalAnd( $result = $searchService->findContent( $query ); ``` -A ` ParentLocationId ` criterion limits the search to the children of location 2. An array of "`ContentTypeId"` Criteria to limit the search to Content of ContentType's with id 1 or 2 grouped in a `LogicalOr` operator. Those two criteria are grouped with a `LogicalAnd` operator. As always the query is executed as before, with `SearchService::findContent()`. +A `ParentLocationId` criterion limits the search to the children of location 2. An array of "`ContentTypeId"` Criteria to limit the search to Content of ContentType's with id 1 or 2 grouped in a `LogicalOr` operator. Those two criteria are grouped with a `LogicalAnd` operator. As always the query is executed as before, with `SearchService::findContent()`. Want to do a subtree filter? Change the location filter to use the Subtree criterion filter as shown in the advanced search example above. -  - -#### Using in() instead of OR +##### Using in() instead of OR The above example is fine, but it can be optimized a bit by taking advantage of the fact that all filter criteria support being given an array of values (IN operator) instead of a single value (EQ operator). @@ -699,22 +889,20 @@ $result = $searchService->findContent( $query ); All filter criteria are capable of doing an "IN" selection, the ParentLocationId above could, for example, have been provided "array( 2, 43 )" to include second level children in both your content tree (2) and your media tree (43). -### Performing a Faceted Search - -Under construction +#### Performing a Faceted Search -Faceted Search is not fully implemented yet, +!!! note "Under construction" -- Implemented Facets SOLR BUNDLE >=1.4:` User, ContentType, & Section ` , see:   [![](https://jira.ez.no/images/icons/issuetypes/epic.png)EZP-26465](https://jira.ez.no/browse/EZP-26465?src=confmacro) - Search Facets M1 Development -- Not Implemented Facets: `CriterionFacet, DateRangeFacet, FieldFacet, FieldRangeFacet, LocationFacet (meant for Location search), & TermFacet` + Faceted Search is not fully implemented yet. -` ` + - Implemented Facets SOLR BUNDLE >=1.4: `User, ContentType, & Section` , see:   [![](https://jira.ez.no/images/icons/issuetypes/epic.png)EZP-26465](https://jira.ez.no/browse/EZP-26465?src=confmacro) - Search Facets M1 Development + - Not Implemented Facets: `CriterionFacet, DateRangeFacet, FieldFacet, FieldRangeFacet, LocationFacet (meant for Location search), & TermFacet` -You can register [custom facet builder visitors](https://github.com/ezsystems/ezplatform-solr-search-engine/blob/v1.1.1/lib/Resources/config/container/solr/facet_builder_visitors.yml) with Solr for Content(Info) and SOLR BUNDLE >=1.4 Location search. + You can register [custom facet builder visitors](https://github.com/ezsystems/ezplatform-solr-search-engine/blob/v1.1.1/lib/Resources/config/container/solr/facet_builder_visitors.yml) with Solr for Content(Info) and SOLR BUNDLE >=1.4 Location search. -Contribution starting point + **Contribution starting point** -The link above is also the starting point for contributing visitors for other API [FacetBuilders](https://github.com/ezsystems/ezpublish-kernel/tree/master/eZ/Publish/API/Repository/Values/Content/Query/FacetBuilder) and [Facets](https://github.com/ezsystems/ezpublish-kernel/tree/master/eZ/Publish/API/Repository/Values/Content/Search/Facet) . As for integration tests, fixtures that will need adjustments are found in [ezpublish-kernel](https://github.com/ezsystems/ezpublish-kernel/tree/master/eZ/Publish/API/Repository/Tests/_fixtures/Solr) , and those missing in that link but [defined in SearchServiceTest](https://github.com/ezsystems/ezpublish-kernel/blob/master/eZ/Publish/API/Repository/Tests/SearchServiceTest.php#L2474), are basically not implemented yet. + The link above is also the starting point for contributing visitors for other API [FacetBuilders](https://github.com/ezsystems/ezpublish-kernel/tree/master/eZ/Publish/API/Repository/Values/Content/Query/FacetBuilder) and [Facets](https://github.com/ezsystems/ezpublish-kernel/tree/master/eZ/Publish/API/Repository/Values/Content/Search/Facet) . As for integration tests, fixtures that will need adjustments are found in [ezpublish-kernel](https://github.com/ezsystems/ezpublish-kernel/tree/master/eZ/Publish/API/Repository/Tests/_fixtures/Solr) , and those missing in that link but [defined in SearchServiceTest](https://github.com/ezsystems/ezpublish-kernel/blob/master/eZ/Publish/API/Repository/Tests/SearchServiceTest.php#L2474), are basically not implemented yet. To be able to take advantage of facets, we can set the `Query->facetBuilders` property, which will result in relevant facets being returned on `SearchResult->facets`. All facet builders share the following properties: @@ -722,7 +910,7 @@ To be able to take advantage of facets, we can set the `Query->facetBuilders` pr - `minCount`: Optional, the minimum of hits of a given grouping, e.g. minimum number of content items in a given facet for it to be returned - `limit`: Optional, Maximum number of facets to be returned; only X number of facets with the greatest number of hits will be returned. -As an example, let's `apply UserFacet ` to be able to group content according to the creator: +As an example, let's `apply UserFacet` to be able to group content according to the creator: ``` php use eZ\Publish\API\Repository\Values\Content\Query\Criterion; @@ -745,13 +933,11 @@ $result = $searchService->findContentInfo( $query ); list( $userId, $articleCount ) = $result->facets[0]->entries; ``` -### Performing a pure search count +#### Performing a pure search count In many cases you might need the number of Content items matching a search, but with no need to do anything else with the results. -Thanks to the fact that the " searchHits " property of the [`SearchResult`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Search/SearchResult.html) object always refers to the total amount, it is enough to run a standard search and set $limit to 0. This way no results will be retrieved, and the search will not be slowed down, even when the number of matching results is huge. - -  +Thanks to the fact that the "searchHits" property of the [`SearchResult`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/Search/SearchResult.html) object always refers to the total amount, it is enough to run a standard search and set $limit to 0. This way no results will be retrieved, and the search will not be slowed down, even when the number of matching results is huge. ``` php use eZ\Publish\API\Repository\Values\Content\Query; @@ -766,13 +952,11 @@ $query->limit = 0; $resultCount = $searchService->findContent( $query )->totalCount; ``` - -# Managing Content - +## Managing Content In the following recipes, you will see how to create Content, including complex fields like XmlText or Image. -## Identifying to the repository with a login and a password +### Identifying to the repository with a login and a password As seen earlier, the Repository executes operations with a user's credentials. In a web context, the currently logged-in user is automatically identified. In a command line context, you need to manually log a user in. We have already seen how to manually load and set a user using its ID. If you would like to identify a user using their username and password instead, this can be achieved in the following way: @@ -795,11 +979,11 @@ $user = $userService->loadUserByCredentials( $username, $password ); $permissionResolver->setCurrentUserReference($user); ``` -## Creating content +### Creating content -Full code +!!! note "Full code" - + We will now see how to create Content using the Public API. This example will work with the default Folder (ID 1) Content Type from eZ Platform. @@ -813,7 +997,7 @@ $contentTypeService = $repository->getContentTypeService(); We first need the required services. In this case: `ContentService`, `LocationService` and `ContentTypeService`. -### The ContentCreateStruct +#### The ContentCreateStruct As explained in [eZ Platform Public PHP API](eZ-Platform-Public-PHP-API_31429583.html), Value Objects are read only. Dedicated objects are provided for Update and Create operations: structs, like `ContentCreateStruct` or `UpdateCreateStruct`. In this case, we need to use a `ContentCreateStruct`.  @@ -824,7 +1008,7 @@ $contentCreateStruct = $contentService->newContentCreateStruct( $contentType, 'e We first need to get the [`ContentType`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/ContentType/ContentType.html) we want to create a `Content` with. To do so, we use [`ContentTypeService::loadContentTypeByIdentifier()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/ContentTypeService.html#method_loadContentTypeByIdentifier), with the wanted `ContentType` identifier, like 'article'. We finally get a ContentTypeCreateStruct using [`ContentService::newContentCreateStruct()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/ContentService.html#method_newContentCreateStruct), providing the Content Type and a Locale Code (eng-GB). -### Setting the fields values +#### Setting the fields values ``` php $contentCreateStruct->setField( 'title', 'My title' ); @@ -834,11 +1018,11 @@ $contentCreateStruct->setField( 'body', $body ); Using our create struct, we can now set the values for our Content item's Fields, using the [`setField()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/ContentCreateStruct.html#method_setField) method. For now, we will just set the title. `setField()` for a TextLine Field simply expects a string as input argument. More complex Field Types, like Author or Image, expect different input values. -The ` ContentCreateStruct::setField() ` method can take several type of arguments. +The `ContentCreateStruct::setField()` method can take several type of arguments. In any case, whatever the Field Type is, a Value of this type can be provided. For instance, a TextLine\\Value can be provided for a TextLine\\Type. Depending on the Field Type implementation itself, more specifically on the `fromHash()` method every Field Type implements, various arrays can be accepted, as well as primitive types, depending on the Type. -## Setting the Location +#### Setting the Location In order to set a Location for our object, we must instantiate a [`LocationCreateStruct`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/Values/Content/LocationCreateStruct.html). This is done with `LocationService::newLocationCreateStruct()`, with the new Location's parent ID as an argument. @@ -846,7 +1030,7 @@ In order to set a Location for our object, we must instantiate a [`LocationCreat $locationCreateStruct = $locationService->newLocationCreateStruct( 2 ); ``` -## Creating and publishing +#### Creating and publishing To actually create our Content in the Repository, we need to use `ContentService::createContent()`. This method expects a `ContentCreateStruct`, as well as a `LocationCreateStruct`. We have created both in the previous steps. @@ -859,7 +1043,7 @@ The LocationCreateStruct is provided as an array, since a Content item can have `createContent()`returns a new Content Value Object, with one version that has the DRAFT status. To make this Content visible, we need to publish it. This is done using `ContentService::publishVersion()`. This method expects a `VersionInfo` object as its parameter. In our case, we simply use the current version from `$draft`, with the `versionInfo` property. -## Updating Content +### Updating Content Full code @@ -891,7 +1075,7 @@ $content = $contentService->publishVersion( $contentDraft->versionInfo ); We can now use `ContentService::updateContent()` to apply our `ContentUpdateStruct` to our draft's `VersionInfo`. Publishing is done exactly the same way as for a new content, using `ContentService::publishVersion()`. -## Handling translations +### Handling translations In the two previous examples, you have seen that we set the ContentUpdateStruct's `initialLanguageCode` property. To translate an object to a new language, set the locale to a new one. @@ -920,11 +1104,11 @@ $contentUpdateStruct->setField( 'body', $newfrenchbody ); Since we don't specify a locale for the last two fields, they are set for the `UpdateStruct`'s `initialLanguageCode`, fre-FR. -## Creating Content containing an image +### Creating Content containing an image -Full code +!!! note "Full code" - + As explained above, the `setField()` method can accept various values: an instance of the Field Type's Value class, a primitive type, or a hash. The last two depend on what the `Type::acceptValue()` method is build up to handle. TextLine can, for instance, accept a simple string as an input value. In this example, you will see how to set an Image value. @@ -967,11 +1151,11 @@ $contentCreateStruct->setField( 'image', array( ); ``` -## Create Content with XML Text +### Create Content with XML Text -Full code +!!! note "Full code" - + Another very commonly used Field Type is the rich text one, `XmlText`. @@ -990,20 +1174,22 @@ $contentCreateStruct->setField( 'body', $xmlText ); As for the last example above, we use the multiple formats accepted by `setField()`, and provide our XML string as is. The only accepted format as of 5.0 is internal XML, the one stored in the Legacy database. -The XSD for the internal XML representation can be found in the kernel: . +!!! note + + The XSD for the internal XML representation can be found in the kernel: . We embed an image in our XML, using the `` tag, providing an image Content ID as the `object_id` attribute. -Using a custom format as input +!!! note "Using a custom format as input" -More input formats will be added later. The API for that is actually already available: you simply need to implement the [`XmlText\Input`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/Core/FieldType/XmlText/Input.html) interface. It contains one method, [`getInternalRepresentation()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/Core/FieldType/XmlText/Input.html#method_getInternalRepresentation), that must return an internal XML string. Create your own bundle, add your implementation to it, and use it in your code! + More input formats will be added later. The API for that is actually already available: you simply need to implement the [`XmlText\Input`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/Core/FieldType/XmlText/Input.html) interface. It contains one method, [`getInternalRepresentation()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/Core/FieldType/XmlText/Input.html#method_getInternalRepresentation), that must return an internal XML string. Create your own bundle, add your implementation to it, and use it in your code! ``` php $input = new \My\XmlText\CustomInput( 'My custom format string' ); $contentCreateStruct->setField( 'body', $input ); ``` -## Deleting Content +### Deleting Content ``` php $contentService->deleteContent( $contentInfo ); @@ -1011,13 +1197,13 @@ $contentService->deleteContent( $contentInfo ); [`ContentService::deleteContent()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/ContentService.html#method_deleteContent) method expects a `ContentInfo` as an argument. It will delete the given Content item, all of its Locations, as well as all of the Content item's Locations' descendants and their associated Content. -Use with caution! +!!! caution + Use with caution! -# Working with Locations +## Working with Locations - -## Adding a new Location to a Content item +### Adding a new Location to a Content item Full code @@ -1067,11 +1253,11 @@ $newLocation = $locationService->createLocation( $contentInfo, $locationCreateSt We finally use `LocationService::createLocation()`, providing the `ContentInfo` obtained above, together with our `LocationCreateStruct`. The method returns the newly created Location Value Object. -## Hide/Unhide Location +### Hide/Unhide Location -Full code +!!! note "Full code" - + We mentioned earlier that a Location's visibility could be set while creating the Location, using the hidden property of the LocationCreateStruct. Changing a Location's visibility may have a large impact in the Repository: doing so will affect the Location's subtree visibility. For this reason, a `LocationUpdateStruct` doesn't let you toggle this property. You need to use the `LocationService` to do so. @@ -1084,7 +1270,7 @@ There are two methods for this: `LocationService::hideLocation`, and `LocationSe The explanation above is valid for most Repository objects. Modification of properties that affect other parts of the system will require that you use a custom service method. -## Deleting a Location +### Deleting a Location Deleting Locations can be done in two ways: delete, or trash.  @@ -1102,7 +1288,7 @@ $trashService->trash( $locationInfo ); The `TrashService` can be used to list, restore and delete Locations that were previously sent to Trash using [`TrashService::trash()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/TrashService.html#method_trash). -## Setting a content item's main Location +### Setting a content item's main Location This is done using the `ContentService`, by updating the `ContentInfo` with a `ContentUpdateStruct` that sets the new main location: @@ -1119,15 +1305,13 @@ $contentService->updateContentMetadata( $contentInfo, $contentUpdateStruct ); Credits to [Gareth Arnott](https://doc.ez.no/display/~arnottg) for the snippet. +## Other recipes -# Other recipes +### Assigning Section to content +!!! note "Full code" -## Assigning Section to content - -Full code - -[https://github.com/ezsystems/CookbookBundle/tree/master/Command/AssignContentToSectionCommand.php](https://github.com/docb22/ez-publish-cookbook/tree/master/EzSystems/CookBookBundle/Command/AssignContentToSectionCommand.php) + [https://github.com/ezsystems/CookbookBundle/tree/master/Command/AssignContentToSectionCommand.php](https://github.com/docb22/ez-publish-cookbook/tree/master/EzSystems/CookBookBundle/Command/AssignContentToSectionCommand.php) The Section that a Content item belongs to can be set during creation, using the `ContentCreateStruct::$sectionId` property. However, as for many Repository objects properties, the Section can't be changed using a `ContentUpdateStruct`. The reason is still the same: changing a Content item's Section will affect the subtrees referenced by its Locations. For this reason, it is required that you use the SectionService to change the Section of a Content item. @@ -1167,11 +1351,11 @@ The actual update operation is done using `SectionService::assignSection()`, wit `SectionService::assignSection()` won't return the updated Content, as it has no knowledge of those objects. To get the Content with the newly assigned Location, you need to reload the `ContentInfo` using [`ContentService::loadContentInfo()`](http://apidoc.ez.no/sami/trunk/NS/html/eZ/Publish/API/Repository/ContentService.html#method_loadContentInfo). This is also valid for descendants of the Content item. If you have any stored in your execution state, you need to reload them. Otherwise you would be using outdated Content data. -## Creating a Content Type +### Creating a Content Type -Full code +!!! note "Full code" - + Creating a `ContentType` is actually almost more complex than creating Content. It really isn't as common, and didn't "deserve" the same kind of API as Content did. diff --git a/docs/api/rest_api_guide.md b/docs/api/rest_api_guide.md index 5d2a504a81..1a4e5b8015 100644 --- a/docs/api/rest_api_guide.md +++ b/docs/api/rest_api_guide.md @@ -1,18 +1,14 @@ - - # REST API Guide - - The REST API v2 introduced in eZ Platform allows you to interact with an eZ Platform installation using the HTTP protocol, following a [REST](http://en.wikipedia.org/wiki/Representational_state_transfer) interaction model. ## Accessing the REST API -The REST API is available at the URI `/api/ezp/v2` . HTTPS is available as long as your server is properly configured. Refer to the [Getting started with the REST API](Getting-started-with-the-REST-API_31430289.html) page to start using the API. +The REST API is available at the URI `/api/ezp/v2` . HTTPS is available as long as your server is properly configured. Refer to the [Getting started with the REST API](#getting-started-with-the-rest-api) page to start using the API. ## Basics -REST (**RE**presentational **S**tate **T**ransfer) is a web services architecture that follows the HTTP Protocol very closely. The eZ Platform REST API supports both [JSON](http://www.json.org/) and [XML](http://www.w3.org/XML/) in terms of request format. +REST (REpresentational State Transfer) is a web services architecture that follows the HTTP Protocol very closely. The eZ Platform REST API supports both [JSON](http://www.json.org/) and [XML](http://www.w3.org/XML/) in terms of request format. ### Resources @@ -22,53 +18,47 @@ The API provides a set of URIs, each of them identifying and providing access to It uses HTTP verbs ( **`GET`** , **`POST`** , but also **`PUT`** , **`DELETE`** , etc...), as well as HTTP headers to specify the type of request. Depending on the used HTTP verb, different actions will be possible. Example: -- ` GET /content/objects/2 ` will provide you with data about Content \#2, -- ` PATCH /content/objects/2 ` will update the Content \#2's metadata (section, main language, main location...), -- ` DELETE /content/objects/2 ` will delete Content \#2, -- ` COPY /content/objects/2 ` will create a copy of this Content. - -Caution with custom HTTP verbs +- `GET /content/objects/2` will provide you with data about Content \#2, +- `PATCH /content/objects/2` will update the Content \#2's metadata (section, main language, main location...), +- `DELETE /content/objects/2` will delete Content \#2, +- `COPY /content/objects/2` will create a copy of this Content. -Using custom HTTP verbs, those besides the standard (GET, POST, PUT, DELETE, OPTIONS, TRACE), can cause issues with several HTTP proxies, network firewall/security solutions and simpler web servers. To avoid issues with this REST API allows you to set these using a HTTP header instead using HTTP verb POST. Example: `X-HTTP-Method-Override: PUBLISH` +!!! note "Caution with custom HTTP verbs" -  + Using custom HTTP verbs, those besides the standard (GET, POST, PUT, DELETE, OPTIONS, TRACE), can cause issues with several HTTP proxies, network firewall/security solutions and simpler web servers. To avoid issues with this REST API allows you to set these using a HTTP header instead using HTTP verb POST. Example: `X-HTTP-Method-Override: PUBLISH` ### Media type headers On top of verbs, HTTP request headers will allow you to personalize the request's behavior. On every resource, you can use the Accept header to indicate which format you want to communicate in, JSON or XML. This header is also used to specify the response type you want the server to send when multiple ones are available. -- `Accept: application/vnd.ez.api.Content+xml ` to get **Content** (full data, fields included) as **XML** -- `Accept: application/vnd.ez.api.ContentInfo+json ` to get **ContentInfo** (metadata only) as **JSON** +- `Accept: application/vnd.ez.api.Content+xml` to get **Content** (full data, fields included) as **XML** +- `Accept: application/vnd.ez.api.ContentInfo+json` to get **ContentInfo** (metadata only) as **JSON** -More information +!!! note "More information" -[REST specifications chapter "Media Types"](https://github.com/ezsystems/ezp-next/blob/master/doc/specifications/rest/REST-API-V2.rst#111%C2%A0%C2%A0%C2%A0media-types) + [REST specifications chapter "Media Types"](https://github.com/ezsystems/ezp-next/blob/master/doc/specifications/rest/REST-API-V2.rst#111%C2%A0%C2%A0%C2%A0media-types) ### Other headers -Other headers will be used in HTTP requests for specifying the siteaccess to interact with, and of course [authentication credentials](REST-API-Authentication_31430293.html). +Other headers will be used in HTTP requests for specifying the siteaccess to interact with, and of course [authentication credentials](general_rest_usage.md#rest-api-authentication). Responses returned by the API will also use custom headers to indicate information about the executed operation. +## Getting started with the REST API - - - -# Getting started with the REST API - - -## Installation +### Installation No special preparations are necessary to use the REST API. As long as your eZ Platform is correctly configured, the REST API is available on your site using the URI `/api/ezp/v2/`. If you have installed eZ Platform in a subfolder, prepend the path with this subfolder: http://example.com/**sub/folder/ezpublish**/api/ezp/v2/. !!! note -Please note that the `/api/ezp/v2` prefix will be used in all REST hrefs, but not in URIs. -## Configuration + Please note that the `/api/ezp/v2` prefix will be used in all REST hrefs, but not in URIs. + +### Configuration -### Authentication +#### Authentication -As explained in more detail in the [authentication page](REST-API-Authentication_31430293.html), two authentication methods are currently supported: session and basic. By default, session authentication is the active mode, it uses a session cookie. The alternative, basic auth authentication requires a login / password to be sent using basic HTTP authentication. +As explained in more detail in the [authentication page](general_rest_usage.md#rest-api-authentication), two authentication methods are currently supported: session and basic. By default, session authentication is the active mode, it uses a session cookie. The alternative, basic auth authentication requires a login / password to be sent using basic HTTP authentication. To enable basic auth based authentication, you need to edit `app/config/security.yml` and uncomment the configuration block about REST @@ -85,13 +75,13 @@ security: realm: eZ Platform REST API ``` -## Testing the API +### Testing the API A standard web browser is not sufficient to fully test the API. You can, however, try opening the root resource with it, using the session authentication: http://example.com/api/ezp/v2/. Depending on how your browser understands XML, it will either download the XML file, or open it in the browser. To test further, you can use browser extensions, like [Advanced REST client for Chrome](https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo) or [RESTClient for Firefox](https://addons.mozilla.org/firefox/addon/restclient/), or dedicated tools. For command line users, [HTTPie](https://github.com/jkbr/httpie) is a good tool. -### JavaScript example +#### JavaScript example One of the main reasons for this API is to help implement JavaScript / AJAX interaction. You can see here an example of an AJAX call that retrieves ContentInfo (e.g. metadata) for a Content item: @@ -123,6 +113,6 @@ If necessary, substitute` 59` with the Content item ID of an item from your data Note that by default, session authentication is used. This means that the session cookie will be transparently sent together with the request, and every AJAX call will have the same permissions as the currently logged in user. -JavaScript REST Client +!!! note "JavaScript REST Client" -To ease the use of the eZ Platform REST API, we provide a JavaScript REST Client. Its basic usage is explained in [Using the JavaScript REST API Client](Using-the-JavaScript-REST-API-Client_31430299.html). + To ease the use of the eZ Platform REST API, we provide a JavaScript REST Client. Its basic usage is explained in [Using the JavaScript REST API Client](js_client.md#using-the-javascript-rest-api-client). diff --git a/docs/api/rest_api_reference.md b/docs/api/rest_api_reference.md index 981e35d9c5..79c713dd9e 100644 --- a/docs/api/rest_api_reference.md +++ b/docs/api/rest_api_reference.md @@ -1,5 +1,3 @@ - - # REST API reference @@ -27,5 +25,3 @@ Then throughout the chapter, grouped into sub-chapters, is the detailed document - Which headers are supported, and how to use them - Which error codes can occur - Most of the time, a request + response example - -  diff --git a/docs/getting_started/about_composer.md b/docs/getting_started/about_composer.md index 0e10afaaf2..279a9afbc9 100644 --- a/docs/getting_started/about_composer.md +++ b/docs/getting_started/about_composer.md @@ -1,19 +1,14 @@ - -# Using Composer - +# About Composer Keeping your system up-to-date is important to make sure it is running optimally and securely. The update mechanism in eZ software is using the *de facto* standard PHP packaging system called [Composer](https://getcomposer.org/).  This makes it easy to adapt package installs and updates to your workflow, allowing you to test new/updated packages in a development environment, place the changes in your version control system (git, Subversion, Mercurial, etc.), pull in those changes to a staging environment and, when approved, put them in production. -  - - -[Composer](https://getcomposer.org/) is an opensource PHP packaging system to manage dependencies. +!!! note "[Composer](https://getcomposer.org/) is an opensource PHP packaging system to manage dependencies." -This makes it easy to adapt package installs and updates to your workflow, allowing you to test new/updated packages in a development environment, put the changes in your version control system (git, Subversion, Mercurial, etc.), pull in those changes on a staging environment and, when approved, put it in production. + This makes it easy to adapt package installs and updates to your workflow, allowing you to test new/updated packages in a development environment, put the changes in your version control system (git, Subversion, Mercurial, etc.), pull in those changes on a staging environment and, when approved, put it in production. -### Installing Composer +## Installing Composer Composer is a command-line tool, so the main way to install it is via command line from inside the root directory of the (eZ) software: @@ -25,7 +20,7 @@ php -r "readfile('https://getcomposer.org/installer');" | php By doing it this way you will need to execute further Composer commands using `php composer.phar`. If you'd rather prefer to install Composer globally on your machine instead of inside each and every project that uses it, then follow [these instructions in online Composer documentation](https://getcomposer.org/doc/00-intro.md#globally). -### Prerequisite to using composer with eZ Enterprise software +## Prerequisite to using composer with eZ Enterprise software **This section describes features available only in eZ Enterprise.** @@ -52,7 +47,7 @@ Support agreement expiry If your Support agreement expires, your authentication token(s) will no longer work. They will become active again if the agreement is renewed, but this process may take up to 24 hours. (If the agreement is renewed before the expiry date, there will be no disruption of service.) -### Optional: Save authentication information in auth.json to avoid repeatedly typing it +#### Optional: Save authentication information in auth.json to avoid repeatedly typing it Composer will ask to do this for you on updates, however if it is disabled, you can create an `auth.json` file manually in one of the following ways: @@ -68,7 +63,7 @@ composer config http-basic.updates.ez.no composer config --global http-basic.updates.ez.no ``` -### Update workflow Using Composer +## Update workflow Using Composer This section describes the best practice for using Composer, essentially it suggests treating updates like other code/configuration/\* changes on your project, tackling them on a development machine before staging them for rollout on staging/production.   @@ -82,9 +77,9 @@ Updating eZ software via Composer is nothing different then [updating other pro php -d memory_limit=-1 composer.phar update --no-dev --prefer-dist ``` -Tip +!!! tip -This will load in all updated packages, from eZ as well as third-party libraries, both used by eZ and other you may have added. When updating like this it is recommended to take note of what was updated so you have an idea of what you should test before putting the updates into production. + This will load in all updated packages, from eZ as well as third-party libraries, both used by eZ and other you may have added. When updating like this it is recommended to take note of what was updated so you have an idea of what you should test before putting the updates into production. At this stage you might need to manually clear Symfony's `prod` environment class cache (cached interfaces and lazy services) in case the classes/interfaces in it have changed. This can be done in the following way: @@ -96,11 +91,9 @@ rm -f app/cache/prod/*.php When the update has completed and local install is verified to work, make sure to version changes done to the `composer.lock` file (if you use a version control system like *git*). This file contains **all details of which versions are currently used** and makes sure the same version is used among all developers, staging and eventually production when current changes are approved for production (assuming you have a workflow for this). -  +!!! tip -Tip - -In large development teams make sure people don't blindly update and install third party components. This might easily lead to version conflicts on `composer.lock` and can be tiring to fix up if happening frequently. A workflow involving composer install and unit test execution on proposed changes can help avoid most of this, like the Pull Request workflow available via Github/Bitbucket. + In large development teams make sure people don't blindly update and install third party components. This might easily lead to version conflicts on `composer.lock` and can be tiring to fix up if happening frequently. A workflow involving composer install and unit test execution on proposed changes can help avoid most of this, like the Pull Request workflow available via Github/Bitbucket. ### 2. Installing versioned updates on other development machines and/or staging -> production @@ -112,11 +105,11 @@ Installing eZ software packages via Composer is nothing different then [instal php -d memory_limit=-1 composer.phar install --no-dev --prefer-dist ``` -Tip +!!! tip -Here the importance of `composer.lock` comes in, as this command will tell Composer to install packages in exactly the same version as defined in this file. If you don't keep track of `composer.lock`, it will instead just install always the latest version of a package and won't allow you to stage updates before moving towards production. + Here the importance of `composer.lock` comes in, as this command will tell Composer to install packages in exactly the same version as defined in this file. If you don't keep track of `composer.lock`, it will instead just install always the latest version of a package and won't allow you to stage updates before moving towards production. -### General notes on use of Composer +## General notes on use of Composer ### Installing additional packages via Composer @@ -165,19 +158,15 @@ Best practice for Bundles is described in Symfony documentation under [Best Pra - `ezpublish-legacy-extension` | For standalone 4.x (legacy) extensions, to be used with [ezpublish-legacy-installer](https://github.com/ezsystems/ezpublish-legacy-installer) - `ezpublish-bundle | For eZ Publish Platform 5.x bundles, may optionally be a "legacy bundle".` - - - -#### Composer for Frontend Developers - +## Composer for Frontend Developers If you are a web designer or working on the CSS on your website, this page contains is all you need to know about Composer. -[Composer](https://getcomposer.org/) is an opensource PHP packaging system to manage dependencies. +!!! note "[Composer](https://getcomposer.org/) is an opensource PHP packaging system to manage dependencies." -This makes it easy to adapt package installs and updates to your workflow, allowing you to test new/updated packages in a development environment, put the changes in your version control system (git, Subversion, Mercurial, etc.), pull in those changes on a staging environment and, when approved, put it in production. + This makes it easy to adapt package installs and updates to your workflow, allowing you to test new/updated packages in a development environment, put the changes in your version control system (git, Subversion, Mercurial, etc.), pull in those changes on a staging environment and, when approved, put it in production. -#### Troubleshooting +### Troubleshooting You may experience some latency in dependency resolution: everything is going normally. @@ -195,11 +184,11 @@ php -d memory_limit=-1 composer.phar --verbose (-v|vv|vvv) ### Useful commands -### install +#### install The `install` command reads the composer.lock file from the current directory, processes it, and downloads and installs all the libraries and dependencies outlined in that file. If the file does not exist it will look for composer.json and do the same. -### Usage +##### Usage ``` bash php -d memory_limit=-1 composer.phar install --dry-run --prefer-dist @@ -207,17 +196,17 @@ php -d memory_limit=-1 composer.phar install --dry-run --prefer-dist In this example the `dry-run` option is mentioned to prevent you from doing anything critical. (This option outputs the operations but will not execute anything and implicitly enables the verbose mode). -### Documentation with complete usage: +##### Documentation with complete usage: ``` bash php -d memory_limit=-1 composer.phar install [--prefer-source] [--prefer-dist] [--dry-run] [--dev] [--no-dev] [--no-plugins] [--no-custom-installers] [--no-scripts] [--no-progress] [-v|vv|vvv|--verbose] [-o|--optimize-autoloader] [packages1] ... [packagesN] ``` -### Update +#### Update  The `update` command reads the composer.json file from the current directory, processes it, and updates, removes or installs all the dependencies. -### Interesting options: +##### Interesting options: To limit the update operation to a few packages, you can list the package(s) you want to update as such: @@ -231,20 +220,20 @@ php -d memory_limit=-1 composer.phar update vendor/package1 foo/mypackage php -d memory_limit=-1 composer.phar update vendor/package1 foo/* ``` - ## Composer for System Administrators +!!! note "[Composer](https://getcomposer.org/) is an opensource PHP packaging system to manage dependencies." -[Composer](https://getcomposer.org/) is an opensource PHP packaging system to manage dependencies. + This makes it easy to adapt package installs and updates to your workflow, allowing you to test new/updated packages in a development environment, put the changes in your version control system (git, Subversion, Mercurial, etc.), pull in those changes on a staging environment and, when approved, put it in production. -This makes it easy to adapt package installs and updates to your workflow, allowing you to test new/updated packages in a development environment, put the changes in your version control system (git, Subversion, Mercurial, etc.), pull in those changes on a staging environment and, when approved, put it in production. +!!! note "composer.phar or composer?" -composer.phar or composer ? - -The following examples use a `composer install` global command, as alternative use `php composer.phar `. + The following examples use a `composer install` global command, as alternative use `php composer.phar `. Read the answer in the FAQ:[What Composer command-line do you have to use ?](https://doc.ez.no/pages/viewpage.action?pageId=23529122) -See [the Composer documentation](https://getcomposer.org/doc/00-intro.md) for further information +!!! note + + See [the Composer documentation](https://getcomposer.org/doc/00-intro.md) for further information ### Technical prerequisites @@ -252,37 +241,37 @@ Composer requires PHP 5.3.2+ to run. ### Useful Composer commands for System Administrators -Note: as usual with CLI, you can type: +!!! note - $> php composer.phar help [--xml] [--format="..."] [--raw] [command_name] + as usual with CLI, you can type: -to get help for the command. + `$> php composer.phar help [--xml] [--format="..."] [--raw] [command_name]` -  + to get help for the command. On this page you will find some useful commands and an extract of the Composer Documentation. The interesting options part is an extract of available options -## show +#### show The `show` command displays detailed information about a package, or lists all available packages. -### Usage: +##### Usage ``` bash php composer.phar show [-i|--installed] [-p|--platform] [-a|--available] [-s|--self] [-N|--name-only] [-P|--path] [package] [version] ``` -## require +#### require The `require` command adds required packages to your composer.json and installs them. If you do not want to install the new dependencies immediately, you can call it with `--no-update` -### Usage: +##### Usage ``` bash php composer.phar require [--dev] [--prefer-source] [--prefer-dist] [--no-progress] [--no-update] [--update-no-dev] [--update-with-dependencies] [packages1] ... [packagesN] ``` -### Interesting options +##### Interesting options | --prefer-source | Forces installation from package sources when possible, including VCS information. @@ -291,19 +280,17 @@ php composer.phar require [--dev] [--prefer-source] [--prefer-dist] [--no-progre --no-update | Disables the automatic update of the dependencies --update-with-dependencies | Allows inherited dependencies to be updated with explicit dependencies -  - -## search +#### search The `search` command searches for packages by its name. -### Example : +##### Example ``` bash $> php composer.phar search symfony composer ``` - can return to you a list like this: +can return to you a list like this: ``` bash symfony/assetic-bundle Integrates Assetic into Symfony2 @@ -337,17 +324,17 @@ symfony/stopwatch Symfony Stopwatch Component symfony-cmf/symfony-cmf Symfony Content Management Framework ``` -## validate +#### validate The `validate` command validates a given composer.json. -###  Usage +#####  Usage ``` bash $> php composer.phar validate [--no-check-all] [file] ``` -### Interesting options +##### Interesting options |option | description | |-------|-------------| @@ -355,7 +342,7 @@ The `validate` command validates a given composer.json. | --profile | Display timing and memory usage info | | --working-dir (-d) | If specified, use the given directory as a working directory | -# Automate installation +### Automate installation Note that you can add some scripts to the Composer dependencies installation. @@ -380,6 +367,6 @@ The available events are : - **pre-archive-cmd** - **post-archive-cmd** -See [the Composer documentation](https://getcomposer.org/doc/articles/scripts.md) about scripts for more information +!!! note -  + See [the Composer documentation](https://getcomposer.org/doc/articles/scripts.md) about scripts for more information diff --git a/docs/getting_started/ez_enterprise.md b/docs/getting_started/ez_enterprise.md index 6dec3755ce..b84e5c0f42 100644 --- a/docs/getting_started/ez_enterprise.md +++ b/docs/getting_started/ez_enterprise.md @@ -1,50 +1,24 @@ - - -# Get Started with eZ Enterprise +# eZ Enterprise If you are looking for even more than eZ Platform can offer you, eZ Enterprise is the thing for you. A commercial offering, it rests atop eZ Platform and taps into all that it offers. With its intuitive in-page editing to landing page management, it delivers fully integrated tools that help you create and manage content on eZ Platform-powered sites and apps. -  - From the developer's point of view, working with eZ Enterprise is not much different than operating on eZ Platform, because the core of the system remains the same. - -### eZ Enterprise Features +## eZ Enterprise Features -## ![](docs/getting_started/img/Landing_page.png)Landing Pages +### ![](img/Landing_page.png) Landing Pages eZ Enterprise's Studio UI lets you create block-based Landing Pages using drag-and-drop. This makes building them easy for editors even with no web design experience or HTML knowledge, using prebuilt elements such as headers, banners, image galleries, content lists, tags and more. At the same time, developers can customize Landing Pages by creating adaptable layouts and offering their own custom blocks to be placed in them. -  - -## ![](docs/getting_started/img/edit_icon.png)Inline editing +### ![](img/edit_icon.png) Inline editing You can quickly switch between working on and previewing Landing Pages, which makes for comfortable editing and better control of your content. -  - -  - -## ![](docs/getting_started/img/schedule.png)Content scheduling +### ![](img/schedule.png) Content scheduling Using a special Schedule block you can set up content on your Landing Pages to be published according to a custom schedule, at predefined dates and times. A Timeline slider lets you preview what the pages will look like at any time. -  - -  - -## ![](docs/getting_started/img/flex_icon.png)Content creation workflow +### ![](img/flex_icon.png) Content creation workflow Flex Workflow is a collaboration feature. You can send your content draft to any user and let them look through, modify it and send it onward through your review process. - -  - -  - -  -  - -  - -  diff --git a/docs/getting_started/ez_platform_features.md b/docs/getting_started/ez_platform_features.md index 42bfaaf4cc..f7e180e7f4 100644 --- a/docs/getting_started/ez_platform_features.md +++ b/docs/getting_started/ez_platform_features.md @@ -1,9 +1,6 @@ - - # eZ Platform Features - -# Main eZ Platform Features +## Main eZ Platform Features ### [Content model](../guide/content_model.md) @@ -29,18 +26,13 @@ eZ Platform is based on Symfony full stack and takes advantage of Symfony's bund eZ Platform is extensible at all levels, from content model to content rendering to interface. -  - For a comprehensive discussion of all features, take a look at [the Guide to eZ Platform](../guide/guide_to_ez_platform.md). - -# eZ Platform Demo +## eZ Platform Demo When installing eZ Platform you have two distributions to choose from: you can select a clean installation which is empty and instantly ready for you to start working on your own website. Alternatively, you can choose to install a Demo, a sample website that lets you look around and get to know the system. -Installing the Demo is very similar to [creating a clean installation](../getting_started/install_using_composer.md). - -  +Installing the Demo is very similar to [creating a clean installation](install_using_composer.md). ### What's in the Demo? @@ -50,20 +42,15 @@ Feel free to dabble and experiment with your demo installation. However, if you Demo and clean versions of eZ Platform are stored in separate repositories on GitHub: and . -  - -![eZ Platform demo front page](getting_started/img/platform_demo_bundle_demo.png) - -*Front page of the website available in the Demo* +![eZ Platform demo front page](img/platform_demo_bundle_demo.png "Front page of the website available in the Demo") -  -# Using Composer to Install the Demo +### Using Composer to Install the Demo Besides a "clean" eZ Platform installation there is an option to install eZ Platform with demo content. Demo installation is prepared for the presentation of how eZ Platform works and handles the content using real life examples. Installation of eZ Platform Demo is very similar to a standard "clean" installation. Demo provides some previously prepared content and is stored in a separate github repository - you can find it [here.](https://github.com/ezsystems/ezplatform-demo) -Installation requires Composer global installation. You can find more information about using Composer [here.](../getting_started/about_composer.md) +Installation requires Composer global installation. You can find more information about using Composer [here.](about_composer.md) To perform eZ Platform demo installation use commands below in the terminal/bash/command-line interface.  @@ -76,11 +63,11 @@ php app/console ezplatform:install demo Now you can check out the project structure and capabilities of the system. -It is not recommended to start your own project on demo installation. +!!! caution + It is not recommended to start your own project on demo installation. - -# Taking a look around +### Taking a look around Once you have the Demo installed, take a look around it to familiarize yourself with the interface of eZ Platform. @@ -89,20 +76,18 @@ To access the back office of your installation, append `/ez` to its path: <`y username: admin password: publish -## Back office interface overview +#### Back office interface overview The navigation hub at the top lets you switch between eZ Platform interface (Content) and interfaces for eZ Enterprise solutions (Page and Performance), as well as the Admin Panel. -![Navigation hub](getting_started/img/navigation_hub.png) +![Navigation hub](img/navigation_hub.png) The Content mode is the part of the interface which is the main workspace of editors and users. It is responsible for creating, editing and managing content. -Page and Performance modes are available if your have an eZ Enterprise subscription. Take a look at [Get Started with eZ Enterprise](../getting_started/ez_enterprise.md) to learn more. +Page and Performance modes are available if your have an eZ Enterprise subscription. Take a look at [eZ Enterprise](ez_enterprise.md) to learn more. The Admin Panel lets you manage the details of your installation, including building the content model and managing permissions. -  - -## Project structure +#### Project structure -You can also take a look at the way the project files are structured on the example of the Demo Bundle. See [Structuring an eZ Platform Project](https://doc.ez.no/pages/viewpage.action?pageId=31429687) for more information. +You can also take a look at the way the project files are structured on the example of the Demo Bundle. See [Structuring an eZ Platform Project](../guide/best_practices.md) for more information. diff --git a/docs/getting_started/get_started_with_ez_platform.md b/docs/getting_started/get_started_with_ez_platform.md index f0ad3bf0a3..4b5f7369a0 100644 --- a/docs/getting_started/get_started_with_ez_platform.md +++ b/docs/getting_started/get_started_with_ez_platform.md @@ -1,28 +1,11 @@ - # Get Started with eZ Platform +## Quickstart with eZ Platform -# Quickstart with eZ Platform - -**Before you begin: [Requirements & Configuration](https://doc.ez.no/pages/viewpage.action?pageId=31429536)** - -**Getting things set up: [Installation](https://doc.ez.no/display/DEVELOPER/Step+1%3A+Installation)** +**Before you begin: [Requirements & Configuration](requirements_and_system_configuration.md)** -**Learning eZ Platform: [What's Next](https://doc.ez.no/display/DEVELOPER/Step+2%3A+Going+Deeper)** - -** -** +**Getting things set up: [Installation](install_ez_platform.md)** #### Transitioning to eZ Platform -If you've worked with **eZ Publish** (our legacy product) in the past, see [Migration from eZ Publish](Migration-from-eZ-Publish_31430320.html), and a [Feature Comparison](https://doc.ez.no/display/MAIN/Transitioning+from+eZ+Publish+to+eZ+Platform%3A+Feature+Comparison) between eZ Publish (legacy) and eZ Platform (current). - -If you've worked with **other CMS's** before, see [Migrating to eZ Platform](https://doc.ez.no/pages/viewpage.action?pageId=31429532). - -  - -  - -![](docs/getting_started/img/ibex-mountain-small.png) - -  +If you've worked with **eZ Publish** (our legacy product) in the past, see [Migrating from eZ Publish](../migrating/migrating_from_ez_publish.md), and a [Feature Comparison](https://doc.ez.no/display/MAIN/Transitioning+from+eZ+Publish+to+eZ+Platform%3A+Feature+Comparison) between eZ Publish (legacy) and eZ Platform (current).  diff --git a/docs/getting_started/img/ibex_mountain_small.png b/docs/getting_started/img/ibex_mountain_small.png deleted file mode 100644 index 993b9b2f1b..0000000000 Binary files a/docs/getting_started/img/ibex_mountain_small.png and /dev/null differ diff --git a/docs/getting_started/install_ez_platform.md b/docs/getting_started/install_ez_platform.md index ab4a5260c7..60aa89e5dc 100644 --- a/docs/getting_started/install_ez_platform.md +++ b/docs/getting_started/install_ez_platform.md @@ -1,20 +1,15 @@ +# Install eZ Platform - -# Step 1: Installation - - -### Pick What You Need... - -Well, at least the things required to run your chosen distribution: - +## General installation guide for all eZ distributions This installation guide can be followed with any eZ distribution based on the Symfony framework. Here's a list of available distributions from eZ: - Type | Archive | License | GIT/Composer - **eZ Platform** "clean distribution" | [share.ez.no/downloads/downloads](share.ez.no/downloads/downloads) | GPLv2 | [ezsystems/ezplatform](https://github.com/ezsystems/ezplatform) ([INSTALL.md](https://github.com/ezsystems/ezplatform/blob/master/INSTALL.md)) - eZ Platform Demo not suited for production use | Available via Git / Composer | GPLv2 | [ezsystems/ezplatform-demo](https://github.com/ezsystems/ezplatform-demo) - **ez Platform Enterprise Edition** clean distribution | [support.ez.no/Downloads](https://support.ez.no/Downloads) | BUL (requires eZ Enterprise subscribtion) | [ezsystems/ezplatform-ee](https://github.com/ezsystems/ezplatform-ee) ([INSTALL.md](https://github.com/ezsystems/ezstudio/blob/master/INSTALL.md)) - eZ Platform Enterprise Edition Demo | [support.ez.no/Downloads](https://support.ez.no/Downloads) | BUL (requires eZ Enterprise subscribtion) | [ezsystems/ezplatform-ee-demo](https://github.com/ezsystems/ezplatform-ee-demo) +|Type | Archive | License | GIT/Composer| +|------|------|------|------| +|**eZ Platform**
*"clean distribution"* | [share.ez.no/downloads/downloads](share.ez.no/downloads/downloads) | GPLv2 | [ezsystems/ezplatform](https://github.com/ezsystems/ezplatform) ([INSTALL.md](https://github.com/ezsystems/ezplatform/blob/master/INSTALL.md))| +|eZ Platform Demo
*not suited for production use* | Available via Git / Composer | GPLv2 | [ezsystems/ezplatform-demo](https://github.com/ezsystems/ezplatform-demo)| +|**ez Platform Enterprise Edition**
*clean distribution* | [support.ez.no/Downloads](https://support.ez.no/Downloads) | BUL (requires eZ Enterprise subscribtion) | [ezsystems/ezplatform-ee](https://github.com/ezsystems/ezplatform-ee) ([INSTALL.md](https://github.com/ezsystems/ezstudio/blob/master/INSTALL.md))| +|eZ Platform Enterprise Edition Demo
*not suited for production use* | [support.ez.no/Downloads](https://support.ez.no/Downloads) | BUL (requires eZ Enterprise subscribtion) | [ezsystems/ezplatform-ee-demo](https://github.com/ezsystems/ezplatform-ee-demo)| diff --git a/docs/getting_started/install_manually.md b/docs/getting_started/install_manually.md index 11bbb855d8..8b70d0cfa4 100644 --- a/docs/getting_started/install_manually.md +++ b/docs/getting_started/install_manually.md @@ -1,15 +1,10 @@ # Manual Installation Guides - ### Introduction Hi! You are about to install eZ Platform on your machine and this guide is here to make sure that the whole process of preparation and installation is fast and easy. This guide consists of a three paths that differ slightly; you should choose the one that meets your operating system: -[Microsoft Windows](../getting_started/install_manually.md#Manual_Installation_on_Windows), [Mac OS X](../getting_started/install_manually.md#Installation_Guide_for_OS_X) or other [Unix-Based Systems](../getting_started/install_manually.md#Installation_Guide_for_Unix-Based_Systems). - -  - -  +[Microsoft Windows](install_manually.md#manual-installation-on-windows), [Mac OS X](install_manually.md#installation-guide-for-os-x) or other [Unix-Based Systems](install_manually.md#installation-guide-for-unix-based-systems). **Installation guides can be followed with any eZ Symfony distribution, you can find a list of available distributions from eZ in a table below:** @@ -20,18 +15,15 @@ Hi! You are about to install eZ Platform on your machine and this guide is here | eZ Platform Enterprise Edition *- "clean"* | [support.ez.no/Downloads](https://support.ez.no/Downloads) | BUL (***requires eZ Enterprise subscription)*** | [ezsystems/ezplatform-ee](https://github.com/ezsystems/ezplatform-ee) ([INSTALL.md](https://github.com/ezsystems/ezstudio/blob/master/INSTALL.md)) | | eZ Platform Enterprise Edition - *"demo"* | [support.ez.no/Downloads](https://support.ez.no/Downloads) | BUL (***requires eZ Enterprise subscription)*** | [ezsystems/ezplatform-ee-demo](https://github.com/ezsystems/ezplatform-ee-demo) | -  - -# Installation Guide for OS X +## Installation Guide for OS X +### Preparation: -## Preparation: - -### 1. Install MySQL  +#### 1. Install MySQL  Download from the [official MySQL webpage](https://www.mysql.com/) is strongly recommended. -### 2. Set up PHP +#### 2. Set up PHP This step requires the modification of two files: Apache2 configuration file and `php.ini`. These files can be edited using a terminal editor like vi or nano, or a simple text editor such as TextEdit or Atom. @@ -73,7 +65,7 @@ f. Increase `memory_limit` value for eZ Platform: memory_limit = 4G ``` -### 3. Set up virtual host and start Apache2 +#### 3. Set up virtual host and start Apache2 a. Edit Apache2 configuration file: @@ -107,13 +99,13 @@ sudo chmod -R 775 /private/etc/apache2/users sudo chmod 775 /private/etc/apache2 ``` -### 4. Start Apache2 daemon using terminal +#### 4. Start Apache2 daemon using terminal ``` bash sudo apachectl start ``` -### 5. Install Composer globally +#### 5. Install Composer globally Composer is a dependency manager that allows you to install packages directly in the project. It is also checking all packages' versions on a regular basis to make sure they are up-to-date and to avoid inconsistencies. @@ -123,7 +115,7 @@ mkdir -p /usr/local/bin php -d memory_limit=-1 composer.phar ``` -### 6. Create a new database for eZ Platform +#### 6. Create a new database for eZ Platform Create new database (you can substitute `ez1` with the database name you want to use): @@ -131,7 +123,7 @@ Create new database (you can substitute `ez1` with the database name you want t /usr/local/mysql/bin/mysql -u root -e 'create database ez1;' ``` -### 7. Install Brew package manager +#### 7. Install Brew package manager Brew is a package manager for OS X, if you haven't used it already you are going to love what it does! @@ -139,7 +131,7 @@ Brew is a package manager for OS X, if you haven't used it already you are going ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" ``` -### 8. Install additional requirements for eZ Platform +#### 8. Install additional requirements for eZ Platform a. Install PEAR/PECL extension: @@ -181,10 +173,9 @@ e. Enable opcache extension for PHP (suggested, but not required) by adding: zend_extension=opcache.so ``` -## Installation: +### Installation: -### -9. Install eZ Platform +#### 9. Install eZ Platform a. Go to the folder with your installation and set up directory permissions: @@ -194,8 +185,6 @@ chmod 775 ../../workspace chmod 775 ../../../Documents ``` -  - b. Download archive from [share.ez.no/downloads](http://share.ez.no/downloads/downloads). Extract the eZ Platform archive to a directory, then execute post install scripts. ``` bash @@ -203,8 +192,6 @@ cd // php -d memory_limit=-1 composer.phar run-script post-install-cmd ``` -  - c. Copy the virtual host template: ``` bash @@ -251,7 +238,7 @@ php app/console ezplatform:install clean You will be able to see your page under (or the address you chose in preparation). Please note that a clean install of eZ Platform doesn’t include DemoBundle anymore. -### 10. Optional +#### 10. Optional a. Install PHP 5.6 with opcache extension: @@ -313,17 +300,13 @@ f. Restart Apache: sudo apachectl restart ``` +## Installation Guide for Unix-Based Systems +### 1. Install a LAMP Stack (\*NIX, Apache, MySQL, PHP5+) +Depending on your selected \*NIX distribution, you may need to install part or all of the LAMP stack required to run eZ Platform or eZ Enterprise. Before getting started, make sure you review our [requirements](requirements_and_system_configuration.md) page to see the systems we support and use for testing. You can try using an unsupported configuration, but your results may vary. -# Installation Guide for Unix-Based Systems - - -## 1. Install a LAMP Stack (\*NIX, Apache, MySQL, PHP5+) - -Depending on your selected \*NIX distribution, you may need to install part or all of the LAMP stack required to run eZ Platform or eZ Enterprise. Before getting started, make sure you review our [requirements](https://doc.ez.no/pages/viewpage.action?pageId=31429536) page to see the systems we support and use for testing. You can try using an unsupported configuration, but your results may vary. - -Please not that, while OS X *is* a \*NIX-based system, it has its own unique requirements listed in our [Installation Guide for OS X](../getting_started/install_manually.md#Installation_Guide_for_OS_X). Developer-maintained installation notes are kept in our GitHub repository at this location as well:  +Please not that, while OS X *is* a \*NIX-based system, it has its own unique requirements listed in our [Installation Guide for OS X](install_manually.md#installation-guide-for-os-x). Developer-maintained installation notes are kept in our GitHub repository at this location as well:  You may use your system's package manager (yum, apt-get, etc.) to obtain a copy of Apache, MySQL, and PHP, or download the latest versions from the official websites and install manually: @@ -331,9 +314,9 @@ You may use your system's package manager (yum, apt-get, etc.) to obtain a copy - [MySQL](http://dev.mysql.com/downloads/mysql/) - [PHP 5.6+](http://php.net) -For Debian 8.5, for example, we'd recommend using `apt-get` to install `apache2`, `mysql-server`, `mysql-client`, and `php5-*` (all the packages listed in the [requirements](https://doc.ez.no/pages/viewpage.action?pageId=31429536)), as well as `git` for version control. If the system on which you're doing the install has only 1 or 2 GB of RAM, be sure to [set up swap](https://doc.ez.no/display/DEVELOPER/Set+up+Swap+on+Debian+8.x) so you don't run out of RAM when running the composer scripts later on. +For Debian 8.5, for example, we'd recommend using `apt-get` to install `apache2`, `mysql-server`, `mysql-client`, and `php5-*` (all the packages listed in the [requirements](requirements_and_system_configuration.md)), as well as `git` for version control. If the system on which you're doing the install has only 1 or 2 GB of RAM, be sure to [set up swap](#set-up-swap-on-debian-8xx) so you don't run out of RAM when running the composer scripts later on. -## 2. Get Composer +### 2. Get Composer You'll need Composer, the PHP command line dependency manager. @@ -349,7 +332,7 @@ b. Move the downloaded composer.phar file to a globally-available path: mv composer.phar /usr/local/bin/composer ``` -## 3. Download the desired version of eZ Platform or eZ Enterprise +### 3. Download the desired version of eZ Platform or eZ Enterprise - If you are installing eZ Platform, download the latest archive from  - For licensed eZ Enterprise customers, download your file here:  @@ -365,7 +348,7 @@ git clone https://github.com/ezsystems/ezplatform.git /var/www/ezplatform You can rename the destination folder to whatever you like. This is where eZ Platform will live, and you'll point your virtual host to this folder to use as its root. You may choose to download an archive file from [share.ez.no/downloads](http://share.ez.no/downloads/downloads) instead of cloning from GitHub, and extract the eZ Platform archive to a similar directory. The subsequent steps are identical, regardless of the method you choose to obtain eZ Platform. -## 4. Create a new database for eZ Platform +### 4. Create a new database for eZ Platform Create new database (you can substitute `ezplatform` with the database name you want to use, but keep it in mind as you run the installation script): @@ -373,13 +356,13 @@ Create new database (you can substitute `ezplatform` with the database name yo /usr/bin/mysql -u root -e 'create database ezplatform;' ``` -## 5. Run the Installation Scripts +### 5. Run the Installation Scripts Composer will look inside the composer.json file and install all of the required packages to run eZ Platform. There's a script in the app folder called console that will install eZ Platform for your desired environment as well (dev/prod). -This is the step where you want to make sure you have [swap configured for your machine](https://doc.ez.no/display/DEVELOPER/Set+up+Swap+on+Debian+8.x) if it does not have an abundance of RAM. +This is the step where you want to make sure you have [swap configured for your machine](#set-up-swap-on-debian-8xx) if it does not have an abundance of RAM. -### a. Run composer install: +#### a. Run composer install: ``` bash cd /var/www/ezplatform @@ -390,7 +373,7 @@ Once the installer gets to the point that it creates `app/config/parameters.yml` Next, you'll be asked to specify a database driver. You may press return to accept the default for this option, as well as the next several (`database_host, database_port, database_name, database_user`) unless you have customized those values and need to enter them as configured on your installation. If you set a password for your database user, enter it when prompted for `database_password`. The installer should continue once you've completed this manual portion of the installation process. -### b. Run eZ Platform's installer: +#### b. Run eZ Platform's installer: ``` bash php -d memory_limit=-1 /var/www/ezplatform/app/console ezplatform:install --env prod clean @@ -402,23 +385,23 @@ If Composer asks you for your token, you must log in to your GitHub account and Please note that a clean install of eZ Platform doesn’t include the DemoBundle anymore. -## 6. Setup the folder rights (\*NIX users) +### 6. Setup the folder rights (\*NIX users) Like most things, [Symfony documentation](http://symfony.com/doc/current/book/installation.html#checking-symfony-application-configuration-and-setup) applies here, meaning `app/cache` and `app/logs` need to be writable by cli and web server user. Furthermore, future files and directories created by these two users will need to inherit those access rights. *For security reasons, there is no need for web server to have access to write to other directories.* -Then, go to the [Setup folder rights](../getting_started/install_manually.md#Setup-folder-rights) page for the next steps of this settings. +Then, go to the [Setup folder rights](../getting_started/install_manually.md#setup-folder-rights) page for the next steps of this settings. -## 7. Set up a Virtual Host +### 7. Set up a Virtual Host For our example, we'll demonstrate using Apache2 as part of the traditional LAMP stack. -### Option A: Scripted Configuration +#### Option A: Scripted Configuration -Instead of manually editing the vhost.template file, you may instead [use the included shell script](../getting_started/starting_ez_platform.md#Web-server): /var/www/ezplatform/bin/vhost.sh to generate a configured .conf file. Check out the source of `vhost.sh` to see the options provided. Additional information is included in our [Web Server](../getting_started/starting_ez_platform.md#Web-server) documentation here as well. +Instead of manually editing the vhost.template file, you may instead [use the included shell script](../getting_started/starting_ez_platform.md#Web-server): /var/www/ezplatform/bin/vhost.sh to generate a configured .conf file. Check out the source of `vhost.sh` to see the options provided. Additional information is included in our [Web Server](starting_ez_platform.md#web-server) documentation here as well. -### Option B: Manual Edits +#### Option B: Manual Edits a. Copy the vhost template file from its home in the doc folder: @@ -451,7 +434,7 @@ Be sure to specify `/var/www/ezplatform/web` as the `DocumentRoot` and `Director SetEnvIf Request_URI ".*" SYMFONY_ENV=dev ``` -## 8. Server Configuration (Apache as example) +### 8. Server Configuration (Apache as example) Make sure you've got the `libapache2-mod-php5` module installed for Apache2 to use PHP5.x, and have the rewrite module enabled: @@ -473,31 +456,31 @@ a2ensite ezplatform a2dissite 000-default.conf ``` -## 9. Restart server (Apache) +### 9. Restart server (Apache) ``` bash service apache2 restart ``` -# Setup folder rights +### Setup folder rights For security reasons, there is no need for web server to have access to write to other directories. -## Set the owner and clean directories* +#### Set the owner and clean directories* First, change `www-data` to your web server user. -### Clean the cache/ and logs/ directories +##### Clean the cache/ and logs/ directories ``` bash $ rm -rf app/cache/* app/logs/* ``` -## Use the right option according to your system. +#### Use the right option according to your system. -### A. Using ACL on a *Linux/BSD *system that supports chmod +a +##### A. Using ACL on a *Linux/BSD *system that supports chmod +a **Using ACL on a Linux/BSD system that supports chmod +a** @@ -508,7 +491,7 @@ $ sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inher app/cache app/logs web ``` -### B. Using ACL on a *Linux/BSD *system that does not support chmod +a +##### B. Using ACL on a *Linux/BSD *system that does not support chmod +a Some systems don't support chmod +a, but do support another utility called setfacl. You may need to enable ACL support on your partition and install setfacl before using it (as is the case with Ubuntu), in this way: @@ -521,7 +504,7 @@ $ sudo setfacl -dR -m u:www-data:rwx -m u:`whoami`:rwx \ app/cache app/logs web ``` -### C. Using chown on *Linux/BSD/OS X* systems that don't support ACL +##### C. Using chown on *Linux/BSD/OS X* systems that don't support ACL Some systems don't support ACL at all. You will need to set your web server's user as the owner of the required directories: @@ -533,8 +516,7 @@ $ sudo find {app/{cache,logs},web} -type d | xargs sudo chmod -R 775 $ sudo find {app/{cache,logs},web} -type f | xargs sudo chmod -R 664 ``` -### D. Using chmod on a *Linux/BSD/OS X* system where you can't change owner** -** +##### D. Using chmod on a *Linux/BSD/OS X* system where you can't change owner If you can't use ACL and aren't allowed to change owner, you can use chmod, making the files writable by everybody. Note that this method really isn't recommended as it allows any user to do anything: @@ -555,7 +537,7 @@ It may also possible to add the group ownership inheritance flag so new files in $ sudo chmod g+s {app/{cache,logs},web} ``` -### E. Setup folder rights on Windows +##### E. Setup folder rights on Windows For your choice of web server you'll need to make sure web server user has read access to ``, and write access to the following directories: @@ -563,15 +545,15 @@ For your choice of web server you'll need to make sure web server user has read - app/logs -# Set up Swap on Debian 8.x +### Set up Swap on Debian 8.x Created by David Christian Liedle, last modified on Jul 11, 2016 -# Overview +#### Overview Swap space allows your system to utilize the hard drive to supplement capacity when RAM runs short. Composer install will fail if there is insufficient RAM available, but adding swap will allow it to complete installation. -# Solution +#### Solution Via the command line, you can set up and enable swap on your Debian machine via the following commands (as root): @@ -589,7 +571,7 @@ sysctl vm.vfs_cache_pressure=50 echo "vm.vfs_cache_pressure=50" >> /etc/sysctl.conf ``` -# Testing the Result +#### Testing the Result You should see the changes effected immediately, and can check via the command line: @@ -606,13 +588,11 @@ cat /proc/sys/vm/swappiness cat /proc/sys/vm/vfs_cache_pressure ``` +## Manual Installation on Windows -# Manual Installation on Windows - +### Preparation: -## Preparation: - -### 1. Set up PHP +#### 1. Set up PHP This step requires the modification of two files: Apache2 configuration file and `php.ini`. These files can be edited using a terminal editor like vi or nano, or a simple text editor. file name is **httpd.conf** and by default it is located in this directory: @@ -646,7 +626,7 @@ d. Increase `memory_limit` value for eZ Platform: memory_limit = 4G ``` -### 2. Set up virtual host and start Apache2 +#### 2. Set up virtual host and start Apache2 a. Edit Apache2 configuration file: @@ -673,15 +653,13 @@ d. Add the following line to the file: Include /private/etc/apache2/users/*.conf ``` -  - -### 3. Start Apache2 daemon using Command Line +#### 3. Start Apache2 daemon using Command Line ``` bash httpd.exe ``` -### 4. Install Composer globally +#### 4. Install Composer globally Composer is a dependency manager that allows you to install packages directly in the project. It is also checking all packages' versions on a regular basis to make sure they are up-to-date and to avoid inconsistencies. @@ -690,7 +668,7 @@ curl -sS https://getcomposer.org/installer | php php -d memory_limit=-1 composer.phar ``` -### 5. Create a new database for eZ Platform +#### 5. Create a new database for eZ Platform Create new database (you can substitute `ez1` with the database name you want to use): @@ -698,7 +676,7 @@ Create new database (you can substitute `ez1` with the database name you want mysql -uroot -ppassword -e "CREATE DATABASE ez1" ``` -### 6. Install additional requirements for eZ Platform +#### 6. Install additional requirements for eZ Platform a. Install PEAR/PECL extension: @@ -725,9 +703,9 @@ c. Enable opcache extension for PHP (suggested, but not required) by adding: zend_extension=opcache.so ``` -## Installation: +### Installation: -### 7. Install eZ Platform +#### 7. Install eZ Platform a. Download archive from [share.ez.no/downloads](http://share.ez.no/downloads/downloads). Extract the eZ Platform archive to a directory, then execute post install scripts. @@ -736,8 +714,6 @@ cd // php -d memory_limit=-1 composer.phar run-script post-install-cmd ``` -  - b. Copy the virtual host template: ``` bash diff --git a/docs/getting_started/install_using_composer.md b/docs/getting_started/install_using_composer.md index f26dad6dfc..6c7a225e5d 100644 --- a/docs/getting_started/install_using_composer.md +++ b/docs/getting_started/install_using_composer.md @@ -1,7 +1,5 @@ - # Installation Using Composer - ## Get Composer If you don't have it already, install Composer, the command-line package manager for PHP. You'll have to have a copy of Git installed on your machine. The following command uses PHP to download and run the Composer installer, and should be entered on your terminal and executed by pressing Return or Enter: @@ -10,7 +8,7 @@ If you don't have it already, install Composer, the command-line package manage php -r "readfile('https://getcomposer.org/installer');" | php ``` -For further information about Composer usage see [Using Composer](../getting_started/about_composer.md) . +For further information about Composer usage see [Using Composer](about_composer.md). ## eZ Platform Installation @@ -26,13 +24,14 @@ php app/console ezplatform:install clean php app/console assetic:dump ``` -For more information about the availables options with Composer commands, see[the Composer documentation](https://getcomposer.org/doc/03-cli.md). +!!! note + + For more information about the availables options with Composer commands, see [the Composer documentation](https://getcomposer.org/doc/03-cli.md). -  ### Installing another distribution -eZ Platform exists in several distributions, listed in [Step 1: Installation](../guide/install_ez_platform.md), some with their own installer as shown in the example below. To install the Enterprise Edition you need an eZ Enterprise subscription and have to [set up Composer for that](../getting_started/about_composer.md). +eZ Platform exists in several distributions, listed in [Installation eZ Platform](install_ez_platform.md), some with their own installer as shown in the example below. To install the Enterprise Edition you need an eZ Enterprise subscription and have to [set up Composer for that](about_composer.md). **eZ Platform Enterprise Edition** @@ -84,7 +83,3 @@ cd ezplatform php app/console ezplatform:install demo ``` - - - -  diff --git a/docs/getting_started/requirements_and_system_configuration.md b/docs/getting_started/requirements_and_system_configuration.md index 0cc50b5997..42ff60af22 100644 --- a/docs/getting_started/requirements_and_system_configuration.md +++ b/docs/getting_started/requirements_and_system_configuration.md @@ -1,137 +1,36 @@ +# Requirements and System Configuration +## Platform as a Service (PaaS) -# Step 0: Requirements & System Configuration +If you're using a PaaS provider such as our partner [Platform.sh](https://platform.sh/hosting/php/ez/), where we have an single-server setup, and in the future also clustered setup, you can [skip](starting_ez_platform.md#hello-world) this step. -# Platform as a Service (PaaS) - -If you're using a PaaS provider such as our partner [Platform.sh](https://platform.sh/hosting/php/ez/), where we have an single-server setup, and in the future also clustered setup, you can [skip](https://doc.ez.no/pages/viewpage.action?pageId=31429552) this step. - -# Server +## Server eZ software is built to rely on existing technologies and standards. The minimal setup is `PHP`,  `MySQL/MariaDB`, and `Apache/Nginx`. Recommendation for production setups is to use `Varnish`, and  `Memcached`, `NFS` `and ``Solr` in a [clustered setup](../guide/clustering.md). For supported versions of these technologies see Recommended and Supported setups below. -## Recommended setups +### Recommended setups These setups are tested by QA and are generally recommended setups. For security and performance we furthermore recommend use of the newer versions of components below. -  -Debian - -Ubuntu -RHEL / CentOS -**Operating system** - -8.x "Jessie" - -16.04LTS - -7.x - -**Web Server** - -Nginx 1.6 -Apache 2.4 (prefork\\ mode) - -Nginx 1.10 -Apache 2.4 (prefork\\ mode) - -Nginx 1.8 (latest\\ via\\ [RHSCL](https://access.redhat.com/documentation/en/red-hat-software-collections/)) -Apache 2.4 (prefork\\ mode) - -**DBMS** - -MariaDB 10.0 -MySQL 5.5 - -MySQL 5.7 -MariaDB 10.0 - -MariaDB 10.1 (latest\\ via\\ [RHSCL](https://access.redhat.com/documentation/en/red-hat-software-collections/)) -MariaDB 10.0 (latest\\ via\\ [RHSCL](https://access.redhat.com/documentation/en/red-hat-software-collections/)) -MySQL 5.6 (latest\\ via\\ [RHSCL](https://access.redhat.com/documentation/en/red-hat-software-collections/)) -MariaDB 5.5 - -**PHP** - -PHP 5.6 (via\\ libapache2-mod-php5\\ for\\ Apache) - -PHP 7.0  - -PHP 7.0 (latest\\ via\\ [RHSCL](https://access.redhat.com/documentation/en/red-hat-software-collections/)) - -PHP 5.6 (latest\\ via\\ [RHSCL](https://access.redhat.com/documentation/en/red-hat-software-collections/)) - -**PHP packages** - -php5-cli -php5-fpm (for\\ use\\ with\\ nginx) -php5-readline -php5-mysqlnd *or* php5-pgsql -php5-json -php5-xsl -php5-intl -php5-mcrypt -php5-curl -php5-gd -php5-imagick (optional) -php5-twig (optional,\\ improves\\ performance) -php5-memcached (recommended,\\ improves\\ performance) +||Debian|Ubuntu|RHEL / CentOS| +|------|------|------|------| +|Operating system|8.x "Jessie"|16.04LTS|7.x| +|Web Server|Nginx 1.6
Apache 2.4 *(prefork mode)*|Nginx 1.10
Apache 2.4 *(prefork mode)*|Nginx 1.8 *(latest via [RHSCL](https://access.redhat.com/documentation/en/red-hat-software-collections/))*
Apache 2.4 *(prefork mode)*| +|DBMS|MariaDB 10.0
MySQL 5.5|MySQL 5.7
MariaDB 10.0|MariaDB 10.1 *(latest via RHSCL)*
MariaDB 10.0 *(latest via RHSCL)*
MySQL 5.6 *(latest via RHSCL)*
MariaDB 5.5| +|PHP|PHP 5.6 *(via libapache2-mod-php5 for Apache)*|PHP 7.0|PHP 7.0 *(latest via RHSCL)*
PHP 5.6 *(latest via RHSCL)*| +|PHP packages|php5-cli
php5-fpm *(for use with nginx)*
php5-readline
php5-mysqlnd or php5-pgsql
php5-json
php5-xsl
php5-intl
php5-mcrypt
php5-curl
php5-gd
php5-imagick *(optional)*
php5-twig *(optional, improves performance)*
php5-memcached
*(recommended, improves performance)*|php-cli
php-fpm *(for use with nginx)*
php-readline
php-mysql or php-pgsql
php-json
php-xml
php-mbstring
php-intl
php-mcrypt
php-curl
php-gd or php-imagick
php-memcached *(recommended, via [pecl](https://pecl.php.net/package/memcached))*|php-cli
php-fpm *(for use with nginx)*
php-mysqlnd or php-pgsql
php-xml
php-mbstring
php-process
php-intl
php-pear *(optional, provides pecl)*
php-gd or php-imagick *(via [pecl](https://pecl.php.net/package/imagick))*
php-memcached *(recommended, via [pecl](https://pecl.php.net/package/memcached))*| -php-cli -php-fpm (for\\ use\\ with\\ nginx) -php-readline -php-mysql *or* php-pgsql -php-json -php-xml -php-mbstring -php-intl -php-mcrypt -php-curl -php-gd *or* php-imagick +||| +|------|------| +|Search|Solr (recommended, for better performance and scalability of all API Queries):

Solr 4.10
*Solr 6 SOLR BUNDLE >= 1.3, CURRENTLY TESTED WITH SOLR 6.4.2*

Oracle Java/Open JDK: 7 or 8 (needed for Solr, version 8 recommended)| +|Graphic Handler|GraphicsMagick or ImageMagick or GD| +|[Clustering](../guide/clustering.md)|Linux NFS *(for IO, aka binary files stored in content repository)*
Memcached *(for Persistence cache & Sessions)*
Varnish *(for HttpCache)*| +|Filesystem|Linux ext3 / ext4| +|Package manager|Composer| -php-memcached (recommended,\\ via\\ [pecl](https://pecl.php.net/package/memcached)) - -  - -php-cli -php-fpm (for\\ use\\ with\\ nginx) -php-mysqlnd *or* php-pgsql -php-xml -php-mbstring -php-process -php-intl -php-pear (optional,\\ provides\\ *pecl*) -php-gd *or* php-imagick (via\\ [pecl](https://pecl.php.net/package/imagick)) -php-memcached (recommended,\\ via\\ [pecl](https://pecl.php.net/package/memcached)) - -**Search** -Solr (recommended,\\ for\\ better\\ performance\\ and\\ scalability\\ of\\ all\\ API\\ Queries) - -- Solr 4.10 -- Solr 6 SOLR BUNDLE >= 1.3, CURRENTLY TESTED WITH SOLR 6.4.2 - -Oracle Java/Open JDK: 7 *or* 8 (needed\\ for\\ Solr,\\ [version\\ 8\\ recommended](https://lucene.apache.org/solr/4_10_4/SYSTEM_REQUIREMENTS.html)) - -**Graphic Handler** - -GraphicsMagick *or* ImageMagick *or* GD - -**[Clustering](../guide/clustering.md)** - -Linux NFS\\ (for\\ IO,\\ aka\\ binary\\ files\\ stored\\ in\\ content\\ repository) -Memcached (for\\ Persistence\\ cache\\ &\\ Sessions) -Varnish (for\\ HttpCache) - -**Filesystem** - -Linux ext3 / ext4 - -**Package manager** -Composer - -## Supported setups +### Supported setups WORK IN PROGRESS FOR FUTURE RELEASE, SEE ABOVE FOR NOW @@ -167,14 +66,14 @@ Supported setups are those we perform automated testing on. For security and per - zip - php-memcached *(3.x on PHP 7, 2.2 on PHP 5)* -## Development & Experimental setups +### Development & Experimental setups eZ Platform, the foundation of all eZ software, can theoretically run and execute on many more setups than the ones listed as recommended and supported, including any [operating system supported by PHP](https://wiki.php.net/platforms), on a PHP 5.6 version or higher that pass the [Symfony requirements](http://symfony.com/doc/current/reference/requirements.html), using cache solutions technically supported by [Stash](http://www.stashphp.com/Drivers.html), using databases supported by [Doctrine DBAL](http://doctrine-dbal.readthedocs.org/en/latest/reference/configuration.html#driver), and using a binary file storage solution supported by [FlySystem](https://github.com/thephpleague/flysystem#adapters). Examples of Development setups: - OS: Windows, Mac OS X, Linux -- Filesystem: NTFS, , HFS+, .. +- Filesystem: NTFS, , HFS+, ... Examples of Experimental setups: @@ -184,34 +83,23 @@ Examples of Experimental setups: - IO: S3, Azure, (S)FTP, GridFS, [...](https://flysystem.thephpleague.com/core-concepts/#adapters) - Databases: Postgres, MSSQL, Oracle *(As\\ in\\ technically\\ supported\\ by\\ Doctrine\\ DBAL\\ which\\ we\\ use,\\ but\\ none\\ supported\\ by\\ our\\ installer\\ at\\ the moment,\\ and\\ Oracle\\ and\\ MSSQL\\ is\\ not\\ covered\\ by\\ automated\\ testing)* -  - **While all these options are not supported by eZ Systems**, they are community supported, meaning contributions and efforts made to improve support for these technologies are welcome and can contribute to the technology being supported by the eZ Systems team in the future. -  - -# Client +## Client eZ software is developed to work with *any* web browser that support modern standards, on *any* screen resolution suitable for web, running on *any* device. However for the Editorial and Administration User Interfaces you'll need; a minimum of 1024-by-768 screen resolution, a desktop or tablet device, and a recommended/supported browsers found below. -## Recommended browsers +### Recommended browsers These setups have been undergone some additional manual testing and is known to work. - Mozilla® Firefox® most recent stable version (tested\\ on\\ Firefox\\ 50) - - Google Chrome™ most recent stable version (tested\\ on\\ Chrome\\ 55)  - - Microsoft® Edge® most recent stable version (tested\\ on Edge\\ 38)  -## Supported browsers +### Supported browsers - Apple® Safari® most recent stable version, desktop *and* tablet - - Opera® most recent stable version, or higher, desktop *and* mobile  Please note that the user interface might not look or behave exactly the same across all browsers as it will gracefully degrade if browser does not support certain features. - -  - -  diff --git a/docs/getting_started/starting_ez_platform.md b/docs/getting_started/starting_ez_platform.md index 4156e8dc7d..81fa4303bd 100644 --- a/docs/getting_started/starting_ez_platform.md +++ b/docs/getting_started/starting_ez_platform.md @@ -1,16 +1,10 @@ - - # Starting eZ Platform - - Once you have your eZ Platform installed, all you need to do to start it is to run your Apache server. Then you can access your eZ Platform's front and back office. To access the UI backend, add `/ez` to your installation URL. - -   ## Web Server -## Configuration files +### Configuration files You can find configuration files in the `doc/` directory of the software, for the following web server engines: @@ -26,17 +20,13 @@ and also configuration files for In addition to that, you have a Bash script for generating a virtual host configuration based on template, containing variables among the once define below. For help text, execute: `./bin/vhost.sh -h` -### Help - -  +#### Help ``` bash ./bin/vhost.sh [-h|--help] ``` -  - -### Usage +#### Usage ``` bash $> ./bin/vhost.sh --basedir=/var/www/ezplatform \\ @@ -48,39 +38,38 @@ $> ./bin/vhost.sh --basedir=/var/www/ezplatform \\ Default values will be fetched from the environment variables `$env_list`, but might be overridden using the arguments listed below. -### Arguments - - Option | Description - --basedir= | Root path to where the eZ installation is placed, used for /web - --template-file= | The file to use as a template for the generated output file - --host-name=localhost | Primary host name, default "localhost" - --host-alias=* .localhost | Space separated list of host aliases, default ".localhost" - --ip=127.0.0.1/* | IP address web server should accept traffic on - --port=80 | Port number web server should accept traffic on - --sf-env=prod/dev | Symfony environment used for the virtual host, default is prod - --sf-debug=0/1 | Set if Symfony debug should be on, by default on if env is dev - --trusted-proxies=127.0.0.1/* | Comma separated trusted proxies(e.g. Varnish), that we can get client IP from. - --sf-http-cache=0/1 | To disable Symfony HTTP cache proxy for using a different reverse proxy. By default disabled when env is "dev", enabled otherwise. - --sf-http-cache-class= | To specify a different class than the default one, to use as the Symfony proxy - --sf-classloader-file= | To specify a different class than the default one, to use for PHP auto loading - --body-size-limit =| Limit in megabytes for max sizeof request body, 0 value disables limit - --request-timeout= | Limit in seconds before timeout of request, 0 value disables timeout limit - - +#### Arguments + +|Option | Description| +|-------|------| +|--basedir= | Root path to where the eZ installation is placed, used for /web| +|--template-file= | The file to use as a template for the generated output file| +|--host-name=localhost | Primary host name, default "localhost"| +|--host-alias=* .localhost | Space separated list of host aliases, default ".localhost"| +|--ip=127.0.0.1/* | IP address web server should accept traffic on| +|--port=80 | Port number web server should accept traffic on| +|--sf-env=prod/dev | Symfony environment used for the virtual host, default is prod| +|--sf-debug=0/1 | Set if Symfony debug should be on, by default on if env is dev| +|--trusted-proxies=127.0.0.1/* | Comma separated trusted proxies(e.g. Varnish), that we can get client IP from.| +|--sf-http-cache=0/1 | To disable Symfony HTTP cache proxy for using a different reverse proxy. By default disabled when env is "dev", enabled otherwise.| +|--sf-http-cache-class= | To specify a different class than the default one, to use as the Symfony proxy| +|--sf-classloader-file= | To specify a different class than the default one, to use for PHP auto loading| +|--body-size-limit =| Limit in megabytes for max sizeof request body, 0 value disables limit| +|--request-timeout= | Limit in seconds before timeout of request, 0 value disables timeout limit| ## PHP's built-in server - -## Description +### Description PHP, in 5.4 and later, comes with a [built-in webserver for development purposes](http://php.net/manual/en/features.commandline.webserver.php). This is very handy, as it allows you to **kickstart development quickly**, avoiding having to install and configure [Apache](https://github.com/ezsystems/ezplatform/tree/master/doc/apache2) / [Nginx](https://github.com/ezsystems/ezplatform/tree/master/doc/nginx). All you need here is PHP 5.4+ with command line binary. -## Usage +### Usage Symfony comes with a wrapper script for booting the built-in webserver: `server:run`. It's a nice shortcut as it will correctly set the web root depending on your configuration, and with eZ Platform it can be used as is. -Use this command for **local development purpose only**! -DO NOT use this on production servers, the use of `--env=prod` below is just showcasing that you can use the command both with Symfony's dev and prod environment depending on if you are debugging or just testing out your application locally. +!!! caution "Use this command for **local development purpose only**!" + + DO NOT use this on production servers, the use of `--env=prod` below is just showcasing that you can use the command both with Symfony's dev and prod environment depending on if you are debugging or just testing out your application locally. ##### Examples @@ -100,8 +89,6 @@ The following example will start the webserver on [http://localhost:8000](http: php app/console server:run --env=prod localhost:8000 ``` -  - ##### **Help with the command** As with any Symfony command, you may execute the command with a `-h` flag to get up-to-date help text for the command: @@ -112,29 +99,21 @@ As with any Symfony command, you may execute the command with a `-h` flag to get php app/console server:run -h ``` -  - -  - #### Further reading: - - -# Hello World! +## Hello World! Now your installation is ready and you're on your way to starting work with eZ Platform. To access the back office of your installation, append `/ez` to its path: `/ez>`. You will be prompted for the username and password, which by default are: -username: admin -password: publish - -  +username: `admin` +password: `publish` A clean installation of eZ Platform is empty, so you only get a single page with a rudimentary content model. This is a blank canvas for you to create and customize your own structure. -If you'd like to take a look at an example of using the system to construct a fully functional page, you can also [install eZ Platform with the Demo Bundle](../getting_started/install_ez_platform.md). +If you'd like to take a look at an example of using the system to construct a fully functional page, you can also [install eZ Platform with the Demo Bundle](install_ez_platform.md).   diff --git a/docs/getting_started/troubleshooting.md b/docs/getting_started/troubleshooting.md index 63202493cf..50b34ac744 100644 --- a/docs/getting_started/troubleshooting.md +++ b/docs/getting_started/troubleshooting.md @@ -1,16 +1,12 @@ - - # Avoiding Problems - - WORK-IN-PROGRESS -This page will list many potential problems and gotchas that you may encounter while installing, configuring, and running eZ Platform. If you stumble upon an obstacle, take a look here to see if your case isn't covered. Want to add to this page? Check out our instructions for [contributing to our documentation](https://doc.ez.no/display/DEVELOPER/Contribute+to+Documentation). +This page will list many potential problems and gotchas that you may encounter while installing, configuring, and running eZ Platform. If you stumble upon an obstacle, take a look here to see if your case isn't covered. Want to add to this page? Check out our instructions for [contributing to our documentation](../community_resources/contributing.md#contribute-to-documentation). ## Enable Swap on Systems with Limited RAM -If you're having difficulty completing installation on a system with limited RAM (1GB or 2GB, for example), check that you've enabled swap. This allows your Operating System to use the hard disk to supplement RAM when it runs out. Running \``php -d memory_limit=-1 app/console ezplatform:install --env prod clean`\` on a system with swap enabled should yield success. When a system runs out of RAM, you may see \`Killed\` when trying to clear the cache (e.g., \`php app/console --env=prod cache:clear\` from your project's root directory). +If you're having difficulty completing installation on a system with limited RAM (1GB or 2GB, for example), check that you've enabled swap. This allows your Operating System to use the hard disk to supplement RAM when it runs out. Running `php -d memory_limit=-1 app/console ezplatform:install --env prod clean` on a system with swap enabled should yield success. When a system runs out of RAM, you may see \`Killed\` when trying to clear the cache (e.g., `php app/console --env=prod cache:clear` from your project's root directory). ## Upload Size Limit @@ -22,6 +18,6 @@ For instance, if one of those Field definitions is configured to accept files up ## Initial Install Options -If you accepted all the defaults when doing a \`composer install\`, but realize you need to go back and change some of those options, look in \`app/config/parameters.yml\` – that's where they're stored. +If you accepted all the defaults when doing a `composer install`, but realize you need to go back and change some of those options, look in `app/config/parameters.yml` – that's where they're stored.   diff --git a/mkdocs.yml b/mkdocs.yml index 1ae5b01d61..4cbabb51d7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,7 +11,6 @@ pages: - 'Install eZ Platform': 'getting_started/install_ez_platform.md' - 'Install using Composer': 'getting_started/install_using_composer.md' - 'Install manually': 'getting_started/install_manually.md' - - 'Install using Docker': 'getting_started/install_using_docker.md' - 'Starting eZ Platform': 'getting_started/starting_ez_platform.md' - 'Troubleshooting': 'getting_started/troubleshooting.md' - Going deeper: