Validate a configuration type
+ +Each configuration file is validated against a schema specific to its configuration type. Example: events, which, in earlier Magento versions, were configured in `config.xml`, are now configured in `events.xml`. + +Configuration files can be validated both before (optional) and after any merge of multiple files affecting the same configuration type. Unless the validation rules for the individual and merged files are identical, you should provide two schemas for validating the configuration files: + +* Schema to validate an individual +* Schema to validate a merged file + +New configuration files must be accompanied by XSD validation schemas. An XML configuration file and its XSD validation file must have the same name. + +If you must use two XSD files for a single XML file, the names of the schemas should be recognizable and associated with the XML file. + +If you have an `events.xml` file and a first `events.xsd` file, the XSD files for the merged `events.xml` file could be named `events_merged.xsd`. + +To ensure validation of an XML file by appropriate XSD file, you must specify the relative path to the XSD file in the XML file. For example: + +In the Magento system, configuration files are simple to use, easy to troubleshoot, and validated automatically.
-Configuration performance and memory usage are also improved.
-These topics summarize the major features and changes in Magento configuration.
-Migration
-To migrate from earlier Magento versions, you must redefine the configuration files.
- -Configuration files
-The config.xml configuration file used in previous versions of Magento is now divided into smaller files that configure specific behaviors and entities.
This division enables on-demand loading of configuration files. Because Magento no longer loads all configuration instructions at once, Magento now loads some files only when an application file requests a specific configuration type.
-Multiple extensions can declare configuration files that affect the same configuration type, and these multiple configuration files are merged.
-For example, when multiple extensions have events.xml files, event configuration is derived by merging all events.xml files from all extensions.
Validation
-The smaller configuration files are simpler to validate.
- Each configuration file is now validated against a schema specific to its configuration type.
- For example, events, which previously would have been configured in config.xml along with all other configurations, are now configured in a separate file called events.xml.
- The events.xml file is validated during loading against the events.xsd schema file.
-
Magento\Framework\Config
-All configuration files are processed by the Magento Magento\Framework\Config library component, which loads, merges, and validates XML configuration files and converts them to proper array format.
- During configuration loading, Magento\Framework\Config validates configuration files against schemas in XSD format.
- Each XML configuration type has its own XSD schema.
-
Predefined configuration files
-Predefined configuration files include:
+ +#### Contents + +* Overview of module configuration files +* Configuration load and merge +* Configuration types, objects, and interfaces + +Overview of module configuration files
+The responsibilities of the `config.xml` configuration file used in earlier versions of Magento is now divided between several files, located in various module directories. Magento's multiple configuration files load on demand only when a module requests a specific configuration type. + +You can use these files—also referred to as *configuration types*—to customize specific aspects of your module's behavior. + +Multiple modules can declare configuration files that affect the same configuration type (for example, events), and these multiple configuration files are merged. + +Following are common terms used in this topic: +-
-
-
-
config.php Created during the installation of Magento and loaded on every run of your Magento instance.
-This file controls parameters that are specific to each Magento installation, such as connection to database, cryptographic key, database table prefix, session storage configuration.
-These parameters are gathered in a wizard during installation and written to a single
config.php, so your site administrator can configure these values in a single location.
- config.xmlContains the configurations specified in the Stores > Configuration menu in the Admin panel for the default, website, and store scopes of your Magento instance.
-This menu is itself configured by the
-system.xmlfile, which declares the configuration keys for application configuration and defines how they are displayed the in Stores > Configuration.
- di.xmlContains the configurations for dependency injection.
- events.xmlLists observers and the events to which they are subscribed.
-
- routes.xmlLists the routes and routers.
Load order for configuration files
-The following groupings determine the load order of configuration files:
--
-
-
-
The primary configuration files, which give the most basic types of configuration such as the database connection and the cache, are loaded on bootstrap. These include only configuration required for the application to start (such as
-app/etc/di.xml) and installation-specific configuration (such asapp/etc/config.php).
- -
-
Global configuration files are loaded next. They include configuration from all modules common for all application areas, such as settings for which modules are enabled and which routers are used.
-
- -
-
Area-specific configuration files concerning areas such as adminhtml and frontend are loaded after routing (for instance, routes.xml).
-
-
For some specific configuration files loading is not limited to a single one of these stages.
-For instance, di.xml can be loaded at any stage, and config.xml can be loaded either at bootstrap or with the global configuration files.
How configuration files are merged
-Nodes in configuration files are merged based on their fully qualified XPaths, which has a special attribute defined in $idAttributes array declared as identifier.
This identifier must be unique for all nodes nested under the same parent node.
-The following rules apply when you merge two XML documents:
--
-
- Nodes are merged based on name and then identifier attributes. -
- If a file contains multiple nodes with the same identifier, the nodes are distinguished and an error occurs. -
After two XML documents are merged, the resulting document contains all nodes from the original files.
-The second XML file either supplements or overwrites nodes in the first XML file.
-In the following example, the node contents of the second file overwrite node contents of first file if both files contain nodes with same name and identifier.
- -The Magento\Framework\Config component
-Magento\Framework\Config ensures loading, merging, validation, and processing of the configurations. You can change the standard loading procedure by providing your own implementation of its interfaces. Magento\Framework\Config should be used to introduce a new configuration type.
Magento\Framework\Config provides the following interfaces for extension developers to manage configuration files:
-
-
-
-
-\Magento\Framework\Config\DataInterfaceretrieves the configuration data within a scope.
- -
-
-\Magento\Framework\Config\ScopeInterfaceidentifies current application scope and provides information about the scope's data.
- -
-
-\Magento\Framework\Config\FileResolverInterfaceidentifies the set of files to be read by\Magento\Framework\Config\ReaderInterface.
- -
-
-\Magento\Framework\Config\ReaderInterfacereads the configuration data from storage, selects the storage from which it reads.That is, the file system, database, other storage merges the configuration files according to the merging rules, and validates the configuration files with the validation schemas.
-
-
Extend a configuration type
-To extend an existing configuration type in your extension, you create a configuration file within your extension.
- For example, to add an event observer, you create a events.xml file and declare a new observer.
-
Because the event configuration type already exists in Magento, the loader and the events.xsd validating schema are already present and functional.
- Your new events.xml file is automatically collected from your extension and merged with the events.xml files for other Magento extensions.
-
Create a configuration type
-To create new configuration type, create: - -
-
-
- The XML configuration file -
- The XSD schema that validates it at loading -
- A loader -
For example to introduce an adapter for a new search server that enables extensions to configure how its entities are indexed in that server, create:
- --
-
- A loader. -
- An XSD schema. -
- Any other classes that are required for your new type to work. -
- An appropriately named configuration file. For example,
search.xml. This file is read and validated against your schema.
-
search.xml file, it is merged with your file when it loads.
-
-To add a configuration type to the file system, use the default implementation of the \Magento\Framework\Config\ReaderInterface, which is Magento\Framework\Config\Reader\Filesystem. Extend from the default implementation and provide the following parameters:
-
-
-
-
-$fileResolver. Implements\Magento\Framework\Config\FileResolverInterface. This parameter lists the files containing the configurations of your custom type.
- -
-
-$converter. Implements\Magento\Framework\Config\ConverterInterface. This parameter is responsible for converting the XML into the internal array representation of the configurations.
- -
-
-$schemaLocator. Implements\Magento\Framework\Config/SchemaLocatorInterface. This parameter provides the full path to file(s) containing schema(s) for validation of the individual and merged configuration files.
- -
-
-$validationState. Implements\Magento\Framework\Config\ValidationStateInterface. This parameter defines whether a configuration file should be validated. It is provided by the application by default.
- -
-
-$fileName. The name of a file containing custom configuration. Reader looks for the file names specified by this parameter inetcdirectories.
- -
-
-$idAttributes. An array that contains the ID attributes of a node. - For example, to merge the XML files:array( - '</path/to/node>' => '<identifierAttributeName>', - '</path/to/other/node>' => '<identifierAttributeName>', -}
-
- -
-
-$defaultScope. Defines the configuration scope to be read by default. The default value for this parameter is global scope.
-
After you customize ReaderInterface, you can use it to collect, merge, validate, and convert the configuration files to an internal array representation.
Validate a configuration type
-Configuration files can be validated both before (optional) and after any merge of multiple files affecting the same configuration type. Unless the validation rules for the individual and merged files are identical, you should provide two schemas for validating the configuration files:
--
-
- Schema for an individual file validation -
- Schema for a merged file validation -
New configuration files must be accompanied by XSD validation schemas. An XML configuration file and its XSD validation file must have the same name.
-If you must use two XSD files for a single XML file, the names of the schemas should be recognizable and associated with the XML file.
-If you have an events.xml file and a first events.xsd file, the XSD files for the merged events.xml file could be named events_merged.xsd.
To ensure validation of an XML file by appropriate XSD file, you must specify the relative path to the XSD file in the XML file. For example:
- --<config - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:noNamespaceSchemaLocation="../../../../../lib/internal/Magento/Framework/ObjectManager/etc/config.xsd">- -
IDEs can validate your configuration files at both runtime and development time.
- +config.xml is Magento\Framework\App\Config.module.xml files are merged with other module.xml files.) For more information, see Configuration load and merge.adminhtml is an area scope that is loaded with at the stage with other modules' adminhtml configurations. For more information, see Modules and areas.Configuration load and merge
+This section discusses how configuration files are loaded and merged. + +How Magento loads configuration files
+Magento loads configuration files in the following order (all paths are relative to your Magento installation directory): + +* Primary configuration (`app/etc/di.xml`). This file is used to bootstrap Magento. +* Global configurations from modules (`app/code/Configuration file merge
+Nodes in configuration files are merged based on their fully qualified XPaths, which has a special attribute defined in `$idAttributes` array declared as its identifier. This identifier must be unique for all nodes nested under the same parent node. + +Magento's merge algorithm follows: + +* If node identifiers are equal (or if there is no identifier defined), all underlying content in the node (attributes, child nodes, and scalar content) is overridden. +* If node identifiers are not equal, the node is a new child of the parent node. +* If the original document has multiple nodes with the same identifier, an error is triggered because the identifiers cannot be distinguished. + +After configuration files are merged, the resulting document contains all nodes from the original files. + +Configuration types, objects, and interfaces
+The following sections provide information about configuration types, their corresponding configuration objects, and interfaces you can use to work with the objects: + +* Configuration types and objects +* Configuration interfaces + +Configuration types and objects
+The following table shows each configuration type and the Magento configuration object to which it relates. + +| Configuraiton file | +Description | +Stage | +Configuration object | +
|---|---|---|---|
config.php |
+ Deployment configuration | +Loads into memory when Magento initializes | +Has no object, cannot be customized | +
config.xml |
+ System configuration | +primary, global | +Magento\Framework\App\Config | +
di.xml |
+ Dependency injection configuration | +primary, global, area | +Magento\Framework\ObjectManager\Config | +
events.xml |
+ Event/observer configuration | +global, area | +Magento\Framework\Event | +
routes.xml |
+ Route configuration | +area | +Magento\Framework\App\Route\Config | +
Configuration interfaces
+You can interact with configuration files using interfaces under Magento\Framework\Config. You can also use these interfaces if you create a new configuration types. + +`Magento\Framework\Config` provides the following interfaces: + +* Framework\Config\ConverterInterface, which converts the XML into an in-memory array representation of the configurations. +* Framework\Config\DataInterface, which retrieves the configuration data in a specified scope. +* Framework\Config\FileResolverInterface, which identifies the location of files to be read by `\Magento\Framework\Config\ReaderInterface` +* Framework\Config\ReaderInterface, which reads the configuration data from storage and selects the storage from which it reads. + + That is, the file system, database, other storage merges the configuration files according to the merging rules, and validates the configuration files with the validation schemas. + +* Framework\Config\SchemaLocatorInterface, which locates the XSD schema. +* Framework\Config\ScopeListInterface, which returns a list of scopes. +* Framework\Config\ValidationStateInterface, which retrieves the validation state. + +#### Related topics + + * Create or extend configuration types + * Magento's deployment configuration, config.php \ No newline at end of file diff --git a/guides/v1.0/config-guide/config/config-php.md b/guides/v1.0/config-guide/config/config-php.md new file mode 100644 index 00000000000..c0715f4f619 --- /dev/null +++ b/guides/v1.0/config-guide/config/config-php.md @@ -0,0 +1,156 @@ +--- +layout: default +group: config-guide +subgroup: Magento configuration files +title: Magento's deployment configuration, config.php +menu_title: Magento's deployment configuration, config.php +menu_order: 1 +github_link: config-guide/config/config-php.md +--- + + +#### Contents + +* What is config.php? +* config.php contents + +What is config.php?
+`
+
+
+Unlike other configuration files discussed in Module configuration files, `config.php` is loaded into memory when Magento initializes, is not merged with any other files, and cannot be extended.
+
+`config.php` includes the following information:
+
+* Database credentials and connection settings
+* Cache storage settings
+* Enabled cache types
+* Your encryption key
+* Web routing parameters (base URLs, URL path to Magento Admin)
+* List of enabled modules
+* File system paths
+
+config.php is the replacement for local.xml in earlier Magento versions. It contains a declarative array of configuration values.
config.php contents
+`config.php` is a PHP-file that returns a multi-dimensional associative array. This section discusses its structure and contents. + +Segments
+ +On the first hierarchy level of this array are *configuration segments*. A segment has arbitrary content (a scalar value or a nested array) distinguished from each other by an arbitrary key—both the key and its value are defined by the Magento framework. + +Magento\Framework\App\DeploymentConfig merely provides access to these sections but does not allow you to extend them. + +On the next hierarchy level, items in each segment are ordered according to the module sequence definition, which is obtained by merging all modules' configuration files, with the exception of disabled modules. + +Disabled modules are not recognized by Magento; in other words, they don't participate in merging configuration, in dependency injection, events, plug-ins, and so on. Disabled modules do not display in the storefront or Admin and don't affect routing. The only practical difference of a module being disabled and being completely absent in the code base is that a disabled module is found by the autoloader, enabling its classes and constants to be reused in other code. + +The value `1` or `0` indicates whether a module is enabled or disabled. + +A snippet follows: + +{% highlight PHP %} + + array ( + 'Magento_Core' => 1, + 'Magento_Store' => 1, + 'Magento_Theme' => 1, + 'Magento_Authorization' => 1, + 'Magento_Directory' => 1, + 'Magento_Backend' => 1, + 'Magento_Backup' => 1, + 'Magento_Eav' => 1, + 'Magento_Customer' => 1, +... + ), +); ?> +{% endhighlight %} + +Segment details
+The following table provides details about each `config.php` segment and its structure. + +| Segment | +Key | +Structure | +
|---|---|---|
| Database | +db |
+ __/db +|__/connection +| |__/[default] +| |-- host +| |-- dbname +| |-- username +| |-- password +| |-- model [mysql4] +| |-- initStatements [SET NAMES utf8;] +| |-- active [1] +|-- table_prefix |
+
| Resources | +resource |
+ __/resource + |__/default_setup + |-- connection [default] |
+
| Session storage | +session |
+ __/session + |__/save + |-- <files|db> |
+
| Admin URL path | +backend |
+ __/backend + |-- frontName |
+
| Cache storage | +cache |
+ __/cache + |__/frontend + |__/<for future documentation> |
+
| Installation date | +install |
+ Not currently implemented | +
| Encryption key | +encrypt |
+ __/crypt + |-- key |
+
| Module list | +modules |
+ __/modules + |-- <enumerated modules> |
+
| Cache types | +cache_types |
+ __/cache_types + |-- <enumerated cache types> |
+
+
+
+#### Related topic
+
+Module configuration files
\ No newline at end of file
diff --git a/guides/v1.0/extension-dev-guide/create_module.md b/guides/v1.0/extension-dev-guide/create_module.md
new file mode 100644
index 00000000000..aa2f92f9e69
--- /dev/null
+++ b/guides/v1.0/extension-dev-guide/create_module.md
@@ -0,0 +1,70 @@
+---
+layout: default
+group: extension-dev-guide
+subgroup: How To
+title: Create a Module
+menu_title: Create a Module
+menu_order: 4
+github_link: extension-dev-guide/create_module.md
+---
+
+We're working to improve this topic. Use the Edit this page in GitHub link at the top of this page to give us feedback and suggestions.
+Overview
+ +This topic covers the basic steps of creating a new module. Subsequent sections in this Developer's Guide explain how to verify your new module and how to use Composer to package and distribute the module. + +Basic Pre-Requisites
+Before you begin creating your new module, make sure that you have a working installation of Magento 2.0, and the Magento [System Requirements]({{ site.gdeurl }}install-gde/system-requirements.html). + +Also, Magento recommends that you disable caching while performing the following steps. + +Get started
+The main steps to create a module are: + +1. Build the file structure for the module, with the appropriate "building block" directories +2. Create the `module.xml` file, with a namespace and name for the new module + +In subsequent topics, we will discuss which configuration files are needed for your new module. The required configuration files depend on how you plan to use the module: will it be manifested on the storefront UI, or in the Magento Admin panel, or as a backend extension that makes a service call? + + +Build the file structure
+First let's create the <ModuleName> directory. Use a module name that is descriptive, and not too long. + +Next, you can create the `/etc` directory within the `
+
+
+
+Be aware that the standard placement of the <ModuleName> directory within the overall Magento file structure is app/code/<Vendor>/<ModuleName>/etc/. However, if you are creating a new module for distribution, you can just create the <ModuleName> directory and the required directories within it.
Create the new module.xml file
+Now let's create the module itself, in the /etc directory of the module you just created. + +A module declares itself (i.e. defines its name and existence) in the `module.xml` file, located in the Magento install directory at `
+
diff --git a/guides/v1.0/frontend-dev-guide/layouts/xml-instructions.md b/guides/v1.0/frontend-dev-guide/layouts/xml-instructions.md
index 12728021c79..728f8bcdd29 100644
--- a/guides/v1.0/frontend-dev-guide/layouts/xml-instructions.md
+++ b/guides/v1.0/frontend-dev-guide/layouts/xml-instructions.md
@@ -440,7 +440,7 @@ To pass an argument that is an array use the following construction:
</argument>
-Take a look at a sample module created by the Magento Core Team.
+The team is creating a collection of samples to demonstrate technologies introduced in Magento 2. You can edit your Magneto 2 composer.json file to declare a dependency upon this package of sample modules, and then run composer update to download them.
Arguments values set in a layout file can be accessed in templates using the get{ArgumentName}() and has{ArgumentName}() methods. The latter returns a boolean defining whether there's any value set.
+
Arguments values set in a layout file can be accessed in templates using the get{ArgumentName}() and has{ArgumentName}() methods. The latter returns a boolean difining whether there's any value set.
{ArgumentName} is obtained from the name attribute the following way: for getting the value of <argument name="some_string"> the method name is getSomeString().
Example:
diff --git a/guides/v1.0/frontend-dev-guide/templates/template-email.md b/guides/v1.0/frontend-dev-guide/templates/template-email.md
index ea902e9c29b..cc38c31f71d 100644
--- a/guides/v1.0/frontend-dev-guide/templates/template-email.md
+++ b/guides/v1.0/frontend-dev-guide/templates/template-email.md
@@ -1,10 +1,88 @@
---
layout: default
-group:
+group: fedg
subgroup: C_Templates
title: Customizing email templates
menu_title: Customizing email templates
-menu_order: 3
+menu_order: 4
github_link: frontend-dev-guide/templates/template-email.md
---
+
+
Overview
+ +Email templates are not bound to design themes, but creating a custom theme for a store most likely will include customization of email templates as well. Even if use the default templates, there is a change you will definitely need to make; namely you should change the logo used in these templates which is the Magento logo by default. + + +This topic describes how to change the default logo used in default email templates, how to further customize email templates and apply them for a store. + +Changing email logo
+ +To replace the default Magento logo used in the email templates: + +1. In the Magento Admin, navigate to **Stores** > **Configuration** > GENERAL > **Design** > **Transactional Emails** +2. In the **Scope** drop-down list, select the scope for which you want to set a logo (a certain store view, the whole website, or default config). + +2. Load your logo and specify the alternative text for it. +
+
+3. Click the **Save Config** button.
+
+Customizing email templates
+ +To make more serious customization than changing a logo, you need to create a custom template, optionally using a default template as a basis. + +
+
+
+
+To create a custom email template:
+
+1. In the Magento Admin, navigate to **MARKETING** > Communications > **Email Templates**
+2. Click the **Add New Template** button.
+3. If you want to use a default template as a starting point, in the Load default template section, choose the template and click the **Load Template** button. Email templates can be accessed and customized only in the Magento Admin.
+The path to the configuration settings for each default template appears in the **Used as Default For** field in the Template Information section. Make note of this path, because you will later need to update the configuration with the name of the new template.
+
+4. In **Template Name**, enter the name which will be used in the Magento Admin.
+5. In **Template Subject**, add plain text which will be used as a Subject of the emails sent using the template you create. This field can contain system variables.
+5. Customize template content. For details please refer to the next paragraph.
+6. In **Template Styles**, optionally add CSS styles for the template.
+5. Save the template.
+
+Customizing email content
+ +An email template is an HTML snippet, where the content should be enclosed in<body></body>
+
+To add the store and sales related information to a template, use system variables.
+
+System variables are placeholders which are replaced by particular values when the actual email is generated. For example, the {{var order.increment_id}} variable is replaced by the ID of the order for which the email is generated.
+
+
+
+
+
+
+To add a variable to your template content:
+
+1. On the template creation page, click to place the cursor in the text in which to insert the variable.
+2. Click **Insert Variable**. A pop-up containing a list of variables opens, including custom variables. Variables are grouped by the modules they relate to. The following image illustrates a variable list: You can also create your own custom variables and set their values. This is done in the Admin, under System > Custom Variables
+
+
+2. Click the name of the required variable. The variable code is inserted in the template content. + + +
+
+
+
+
+The selection of available variables depends on which template you use as a basis. Alternatively, you can manually insert variables "related" to other templates in your template code if you know the variable code.
+Applying a new template
+ +To use a new template for generating emails, you need to specify it in the in Admin under **Stores** > **Configuration**. + +The further path to the configuration depends on the purpose of the template. +For example, if the template is supposed to be used for sales emails, like new order notification, or invoice, it is configured under **Stores** > **Configuration** > SALES > **Sales Emails**. + +If your template was created using a default one, then the path for configuration was specified on the template creation page in the **Used as Default For** field. + diff --git a/guides/v1.0/frontend-dev-guide/templates/template-override.md b/guides/v1.0/frontend-dev-guide/templates/template-override.md index 887365465e3..20305268648 100644 --- a/guides/v1.0/frontend-dev-guide/templates/template-override.md +++ b/guides/v1.0/frontend-dev-guide/templates/template-override.md @@ -1,55 +1,73 @@ --- layout: default -group: +group: fedg subgroup: C_Templates -title: Templates overriding -menu_title: Templates overriding +title: Templates basic concepts +menu_title: Templates basic concepts menu_order: 3 github_link: frontend-dev-guide/templates/template-override.md --- -How templates are initiated
+Overview
+This topic discusses the main concepts of how default templates work in the Magento application. +The following topics are covered: -Templates are initiated in layout files. +* How templates are initiated +* Root template +* Conventional templates location +* Templates overriding +* Getting argument values from layout + + +How templates are initiated
+ +Templates are usually initiated in layout files. Each layout block has an associated template. -Template is specified in the `template` attribute of theapp/code/Magento/Catalog/view/frontend/layout/catalog_category_view.xml:
<block class="Magento\Catalog\Block\Category\View" name="category.image" template="Magento_Catalog::category/image.phtml"/>-This means that for rendering the `category.image` block the `image.phtml` template stored in the `category` sub-directory of the `Magento_Catalog` templates directory is used. -The templates directory of the `Magento_Catalog` module is `app/code/Magento/Catalog/view/frontend/templates`. +This means that the `category.image` block is rendered by the `image.phtml` template, which is located in the `category` subdirectory of the `Magento_Catalog` module templates directory. -
What about page templates, how are they initiated? +The templates directory of `Magento_Catalog` is `app/code/Magento/Catalog/view/frontend/templates`. The next section describes where templates can be located in general. -
Conventional templates location
-Templates are stored in the following locations: +Conventional templates location
Templates are stored in the following locations: +* Module templates:app/code/<Namespace>/<Module>/view/frontend/templates/<path_to_templates>
+* Theme templates: app/design/frontend/<Vendor>/<theme>/<Namespace>_<Module>/templates/<path_to_templates>
-* Module templates: `app/code/<path_to_templates> might have several levels of directory nesting, or might be empty. Examples:
* `app/code/Magento/Catalog/view/frontend/templates/product/widget/new/content/new_grid.phtml`
* `app/code/Magento/Checkout/view/frontend/templates/cart.phtml`
-Templates for blocks and templates for pages??
-root.phtml
+Templates overriding
+For template files with the same name, the following is true: +theme templates override module templates, and those of a child theme override parent theme templates. + +This mechanism is the basis of the template customization concept in Magento application: to change the output defined by a certain default template, you need to overriding one in your custom theme. + +Overriding templates is described with more details in the Theme Inheritance article. + + +Root template
+ +In Magento there's a special template which serves as root template for all pages in the application:app/code/Magento/Theme/view/base/templates/root.phtml
+
+Unlike other templates, `root.phtml` contains the `doctype` specification and contributes to <head> and <body> sections of all pages rendered by Magento application.
-Template structure
+But similar to other templates, `root.phtml` can be overridden in a theme. +For example, Magento Blank theme contains an overriding root template: -Is there something our target audience (a fdg creating a new theme)should know about a template file structure?
+app/design/frontend/Magento/luma/Magento_Theme/templates/root.phtml
-I In the declaration like following /** - * @var $this \Magento\Framework\View\Element\Html\Link - */ (from app/code/Magento/Theme/view/frontend/templates/link.phtml) what are the requirements for this class being specified or how is it related to the template
-Getting argument values from layout
+Getting argument values from layout
Arguments values set in a layout file can be accessed in templates using theget{ArgumentName}() and has{ArgumentName}() methods. There are more details in the Layout instructions article.
\ No newline at end of file
diff --git a/guides/v1.0/frontend-dev-guide/templates/template-overview.md b/guides/v1.0/frontend-dev-guide/templates/template-overview.md
index f5fcf799037..ddfbef32cd8 100644
--- a/guides/v1.0/frontend-dev-guide/templates/template-overview.md
+++ b/guides/v1.0/frontend-dev-guide/templates/template-overview.md
@@ -1,6 +1,6 @@
---
layout: default
-group:
+group: fedg
subgroup: C_Templates
title: Templates overview
menu_title: Templates
@@ -11,33 +11,35 @@ github_link: frontend-dev-guide/templates/template-overview.md
Introduction to customizing a theme using templates
-Overview
-In Magento application the markup of a certain page is defined by a "layout plus template" bundle. Where layout files control the presence or absence of each content block in a theme. What, specifically, gets rendered inside of that block is controlled by the template files. Most templates do not contain any logic about whether they will or will not be rendered, this is typically handled by the layout files. Once a template is called, it is expected that it will be parsed and displayed. +In Magento application templates are the part of the view layer. Templates define exactly how the content of layout blocks is presented on a page: order, CSS classes, elements grouping, and so on. +In most cases, templates do not contain any logic about whether they will or will not be rendered, this is typically handled by the layout files. Once a template is called in a layout, it will be displayed. -Default Magento templates are PHTML files that contain HTML and PHP defining the logic for visual presentation. And in this guide by the term "a template" we mean a default Magento `.phtml` template. +Default Magento templates are PHTML files.
-
-Once you identify which template file is being used to generate the contents of a specific block, you can modify that template file if desired. Or you can modify the layout file to associate a different template file with a block, which allows you to create completely new template files.
+This chapter describes how to customize templates in your design theme, and provides both the practice reference and the theoretical background of how templates are applied in a Magento store.
-We strongly recommend not change the default templates, because if you do edit them, your changes can be overwritten by the new version of the default files during upgrades.
-The best practice is creating a new design theme and adding your modified templates there.
-Magento template rendering subsystem can support multiple template engines, including the default PHP-based engine for processing PHTML templates.
+The Magento template rendering subsystem supports multiple template engines, including the default PHP-based engine for processing PHTML templates.
Templates overriding
-For template files with the same name the following is true: -theme templates override module templates, and those of a child theme override parent theme templates. +We strongly recommend that you do not change the default templates, because if you do edit them, your changes can be overwritten by the new version of the default files during upgrades. +The best practice is creating a new design theme and adding your modified templates there. + +This chapter contains the following topics: + +* Template customization walkthrough +* Templates basic concepts +* Illustration of customizing templates +* Customizing email templates + -For more details about overriding templates please refer to the Templates overriding article. -A company named OrangeCo created a theme named Orange. The theme files are located in `app/design/frontend/OrangeCo/orange`. -Orange inherits from the Magento Blank theme. diff --git a/guides/v1.0/frontend-dev-guide/templates/template-sample.md b/guides/v1.0/frontend-dev-guide/templates/template-sample.md index 20c371b416c..f97329bb6be 100644 --- a/guides/v1.0/frontend-dev-guide/templates/template-sample.md +++ b/guides/v1.0/frontend-dev-guide/templates/template-sample.md @@ -1,32 +1,36 @@ --- layout: default -group: +group: fedg subgroup: C_Templates -title: Customizing template illustration -menu_title: Customizing template illustration -menu_order: 4 +title: Illustration of customizing templates +menu_title: Illustration of customizing templates +menu_order: 3 github_link: frontend-dev-guide/templates/template-sample.md --- -Sample template customization: changing a layout of the mini shopping cart
-In the default Blank theme, in the mini shopping cart products are listed under the Go to Checkout button, like following: -
+Overview
+This topic contains a step-by-step illustration of solving a typical design customization task using templates. -Let's change this and display the product list before the Go to Checkout button. -The template responsible for displaying the mini-shopping cart is `app/code/Magento/Checkout/view/frontend/templates/cart/minicart.phtml`. -Here is the part of the code we will work with: +Sample template customization: changing a layout of the mini shopping cart
+In the default Blank theme, in the mini shopping cart, products are listed under the **Go to Checkout** button, like following: +
+
+OrangeCo decided they want to change this and display the product list before the **Go to Checkout** button.
+
+The template responsible for displaying the mini-shopping cart is app/code/Magento/Checkout/view/frontend/templates/cart/minicart.phtml.
+Here is the part of the code OrangeCo worked with:
-We will create a new theme and copy the `minicart.phtml` to our theme folder:
-`app/design/frontend/
-When we apply our new theme, the mini shopping cart with products will look like following:
+When the Orange theme was applied, the mini shopping cart with products looked like following:
-
+
diff --git a/guides/v1.0/frontend-dev-guide/templates/template-walkthrough.md b/guides/v1.0/frontend-dev-guide/templates/template-walkthrough.md
index a75ecb9434a..e32976a2a3b 100644
--- a/guides/v1.0/frontend-dev-guide/templates/template-walkthrough.md
+++ b/guides/v1.0/frontend-dev-guide/templates/template-walkthrough.md
@@ -1,42 +1,42 @@
---
layout: default
-group:
+group: fedg
subgroup: C_Templates
-title: Templates customizing walkthrough
-menu_title: Templates customizing walkthrough
+title: Templates customization walkthrough
+menu_title: Templates customization walkthrough
menu_order: 2
-github_link: frontend-dev-guide/templates/template-walkthrough.md
+github_link: frontend-dev-guide/templates/template-overview.md
---
-Introduction
-This article features high-level steps of a template customization. +Overview
+This topic walks you through how to customize a template. -Template customization walkthrough
+Template customization walkthrough
-To customize a template in your theme: +To customize a template: -1. Locate which template is associated with the page/block you want to change using template hints. +1. Locate the template which is associated with the page/block you want to change using template hints. -2. Copy the template to your theme folder, according to the template storing convention:app/design/<Vendor>/<theme>/<Namespace_Module>/templates/<path_to_template>
+2. Copy the template to your theme folder according to the template storing convention.
3. Make the required changes.
To add a new template in a theme:
-1. Add a template in your theme directory according to the conventional location.
+1. Add a template in your theme directory according to the template storing convention.
-2. Assign your template to a block or page in the corresponding layout file.
+2. Assign your template to a block in the corresponding layout file.
Walkthrough illustration: adding a message to the customer review form
-A small customization to illustrate the walkthrough: in their Orange theme the OrangeCo company want to add a short text to the product review form to inspire customers to write reviews. +A small customization to illustrate the walkthrough: in their Orange theme, the OrangeCo company wants to add a short text to the product review form to encourage customers to write reviews. The following image illustrates how the default review form looks like:
-To add the text OrangeCo need to override the default review form template in the Orange theme.
+To add the text, OrangeCo needs to override the default review form template in the Orange theme.
-First, they copy the `form.phtml` template from `app/code/Magento/Review/view/frontend/templates` to the corresponding sub-directory in the Orange theme directory: `app/design/frontend/OrangeCo/orange/Magento_Review/templates`.
+First, they copy the `form.phtml` template from `app/code/Magento/Review/view/frontend/templates` to the corresponding subdirectory in the Orange theme directory: `app/design/frontend/OrangeCo/orange/Magento_Review/templates`.
In the theme `form.phtml` file they add the HTML snippet with the message before the <form>:
diff --git a/guides/v1.0/install-gde/install/composer-clone.md b/guides/v1.0/install-gde/install/composer-clone.md
index d4e1767f1e8..4c06c84da89 100644
--- a/guides/v1.0/install-gde/install/composer-clone.md
+++ b/guides/v1.0/install-gde/install/composer-clone.md
@@ -1,11 +1,11 @@
---
layout: default
group: install
-subgroup: R_Installation
+subgroup: Q_Pre-installation
title: Install Composer and clone the Magento repository
menu_title: Install Composer and clone the Magento repository
menu_node:
-menu_order: 2
+menu_order: 1
github_link: install-gde/install/composer-clone.md
---
@@ -125,8 +125,11 @@ Assuming the web server user owns the Magento 2 file system, use the following s
4. Set permissions:
- find . -type d -exec chmod 700 {} \;
-find . -type f -exec chmod 600 {} \;
+ find . -type d -exec chmod 700 {} \; && find . -type f -exec chmod 600 {} \;
+
+ If you must enter the commands as `sudo`, use:
+
+ sudo find . -type d -exec chmod 700 {} \; && sudo find . -type f -exec chmod 600 {} \;
#### Next step
diff --git a/guides/v1.0/install-gde/install/install-cli-install.md b/guides/v1.0/install-gde/install/install-cli-install.md
new file mode 100644
index 00000000000..97c247dc71d
--- /dev/null
+++ b/guides/v1.0/install-gde/install/install-cli-install.md
@@ -0,0 +1,359 @@
+---
+layout: default
+group: install
+subgroup: T_Command-line installation
+title: Install the Magento software using the command line
+menu_title: Install the Magento software using the command line
+menu_node:
+menu_order: 4
+github_link: install-gde/install/install-cli-install.md
+---
+
+
+Contents
+ +See one of the following sections: + +* Before you start your installation +* First steps +* Installing the Magento software from the command line +* Updating the Magento software +* Reinstalling the Magento software + +Before you start your installation
+ +Before you begin, make sure that: + +1. Your system meets the requirements discussed in Magento System Requirements. +2. You completed all prerequisite tasks discussed in Prerequisites. +3. You installed Composer and cloned the Magento GitHub repository as discussed in Install Composer and clone the Magento GitHub repository. +4. After you log in to the Magento server, switch to the web server user as discussed in Switching to the Apache user. +5. Review the information discussed in Command line installation. + +
+
+
+
+The installer is designed to be run multiple times if necessary so you can:
+
+* Provide different values
+
+ For example, after you configure your web server for Secure Sockets Layer (SSL), you can run the installer to set SSL options.
+* Correct mistakes in previous installations
+* Install Magento in a different database instance
+
+You must install Magento from its setup subdirectory.
+
+
+
+- By default, the installer doesn't overwrite the Magento database if you install the Magento software in the same database instance. You can use the optional
clean_databaseparameter to change this behavior.
+ - If you get errors during the installation, see Troubleshooting.
Installer help commands
+ +Optionally run the following commands to find values for some required options: + +| Installer option | +Command | +
|---|---|
| Language | +php -f index.php help language |
+
| Time zone | +php -f index.php help timezone |
+
| Currency | +php -f index.php help currency |
+
+
+
+
+
+If an error displays when you run these commands, make sure you updated installation dependencies as discussed in Update installation dependencies.
+Installing the Magento software from the command line
+The format of the install command follows: + + php -f index.php install --| Name | +Value | +Required? | +
|---|---|---|
| base_url | +Base URL to use to access your Magento Admin and storefront in the format Note: The scheme (
To access Magento on localhost, you can use either |
+ Yes | +
| backend_frontname | +Path to access the Magento Admin. This path is appended to Base URL.
+For example, if Base URL is http://www.example.com and Admin Path is admin, the Admin Panel's URL is http://www.example.com/admin—provided you configured your web server for server rewrites. |
+ Yes | +
| db_host | +Use any of the following: +
Note: You can optionally specify the database server port in its host name like |
+ Yes | +
| db_name | +Name of the Magento database instance in which you want to install the Magento database tables. | +Yes | +
| db_user | +User name of the Magento database instance owner. | +Yes | +
| db_pass | +Magento database instance owner's password. | +No | +
| db_prefix | +Use only if you're installing the Magento database tables in a database instance that has Magento tables in it already. +In that case, use a prefix to identify the Magento tables for this installation. Some customers have more than one Magento instance running on a server with all tables in the same database. +This option enables those customers to share the database server with more than one Magento installation. |
+ No | +admin_firstname | +Magento administrator user's first name. | +Yes | + +
| admin_lastname | +Magento administrator user's last name. | +Yes | +
| admin_email | +Magento administrator user's e-mail address. | +Yes | +
| admin_username | +Magento administrator user name. | +Yes | +
| admin_password | +Magento administrator user password. | +Yes | +
| language | +Language code to use in the Admin and storefront. (If you have not done so already, you can view the list of language codes by entering php -f index.php help language from the setup directory.) |
+ Yes | +
| currency | +Default currency to use in the storefront. (If you have not done so already, you can view the list of currencies by entering php -f index.php help currency from the setup directory.) |
+ Yes | +
| timezone | +Default time zone to use in the Admin and storefront. (If you have not done so already, you can view the list of time zones by entering php -f index.php help timezone from the setup directory.) |
+ Yes | +
| use_secure | +
|
+ No | +
| base_secure_url | +
|
+ No | +
| use_secure_admin | +
|
+ No | +
| admin_use_security_key | +
|
+ No | +
| enable_modules=<list>} | +Enable modules that are installed but disabled where To enable and disable modules after installing Magento, see Enable and disable modules. +For important information about module dependencies, see About enabling and disabling modules. |
+ No | +
| disable_modules=<list>} | +Disable modules that are installed and enabled where To enable and disable modules after installing Magento, see Enable and disable modules. +For important information about module dependencies, see About enabling and disabling modules. |
+ No | +
| session_save | +Use any of the following: +
|
+ No | +
| key | +If you have one, specify a key to encrypt sensitive data in the Magento database. (This includes passwords and personally identifiable customer information.) If you don't have one, Magento generates one for you. | +No | +
| use_sample_data | +
Sample data installs only if you already enabled the package as discussed in Enable optional Magento sample data . |
+ No | +
| cleanup_database | +To drop database tables before installing the Magento software, specify this parameter without a value. Otherwise, the Magento database is left intact. | +No | +
| db_init_statements | +Advanced MySQL configuration parameter. Uses database initialization statements to run when connecting to the MySQL database. Consult a reference similar to this one before you set any values. | +No | +
| sales_order_increment_prefix | +Specify a string value to use as a prefix for sales orders. Typically, this is used to guarantee unique order numbers for payment processors. | +No | +
+
+
+
+To enable or disable modules after installing Magento, see Enable and disable modules.
+Sample localhost installation
+ +The following example installs Magento with the following options: + +* The Magento software is installed in the `magento2` directory relative to the web server docroot on `localhost` and the path to the Magento Admin is `admin`; therefore: + + Your storefront URL is `http://localhost` and you can access the Magento Admin at `http://localhost/admin` + +* The database server is on the same host as the web server. + + The database name is `magento`, and the user name and password are both `magento` + +* Installs optional sample data + +* The Magento administrator has the following properties: + + * First and last name are is `Magento User` + * User name is `admin` and the password is `iamtheadmin` + * E-mail address is `user@example.com` + +* Default language is `en_US` (U.S. English) +* Default currency is U.S. dollars +* Default time zone is U.S. Central (America/Chicago) + + php -f index.php install --base_url=http://localhost/magento2/ \ + --backend_frontname=admin \ + --db_host=localhost --db_name=magento --db_user=magento --db_pass=magento \ + --admin_firstname=Magento --admin_lastname=User --admin_email=user@example.com \ + --admin_username=admin --admin_password=iamtheadmin --language=en_US \ + --currency=USD --timezone=America/Chicago + + +
+
+
+
+The command must be entered either on a single line or, as in the preceding example, with a \ character at the end of each line.
Updating the Magento software
+This section discusses how to update your Magento software without reinstalling it. To uninstall and reinstall, see the next section. + +You might do this in an development environment especially to get all the latest code changes. + +To update the Magento software: + +2. Log in to your Magento server as a user with permissions to modify files in the Magento file system (for example, the web server user). +3. Save any changes you made to `composer.json` because the following steps will overwrite it: + + cdReinstalling the Magento software
+This section discusses how to uninstall and then reinstall the Magento software. + +To reinstall the Magento software: + +2. Log in to your Magento server as a user with permissions to modify files in the Magento file system (for example, the web server user). +3. Enter the following commands in the order shown: + + cdCreating the Magento deployment configuration
+Magento's deployment configuration, config.php, provides the information Magento needs to initialize and bootstrap. + +You can use this sucommand if: + +* You previously uninstalled the Magento software and you don't want to run the entire installation again +* If you want to create only `config.php` and continue the Magento installation some other way + +To install the deployment configuration: + +1. Complete the tasks discussed in Before you start your installation. + +2. Enter the following command: + + php index.php install-configuration| Name | +Value | +Required? | +
|---|---|---|
| backend_frontname | +Path to access the Magento Admin. This path is appended to Base URL.
+For example, if Base URL is http://www.example.com and Admin Path is admin, the Admin Panel's URL is http://www.example.com/admin—provided you configured your web server for server rewrites. |
+ Yes | +
| db_host | +Use any of the following: +
Note: You can optionally specify the database server port in its host name like |
+ Yes | +
| db_name | +Name of the Magento database instance in which you want to install the Magento database tables. | +Yes | +
| db_user | +User name of the Magento database instance owner. | +Yes | +
| db_pass | +Magento database instance owner's password. | +No | +
| db_prefix | +Use only if you're installing the Magento database tables in a database instance that has Magento tables in it already. +In that case, use a prefix to identify the Magento tables for this installation. Some customers have more than one Magento instance running on a server with all tables in the same database. +This option enables those customers to share the database server with more than one Magento installation. |
+ No | +
| session_save | +Use any of the following: +
|
+ No | +
| key | +If you have one, specify a key to encrypt sensitive data in the Magento database. (This includes passwords and personally identifiable customer information.) If you don't have one, Magento generates one for you. | +No | +
| enable_modules=<list> | +Enable modules that are installed but disabled where For important information about module dependencies, see About enabling and disabling modules. |
+ No | +
| disable_modules=<list> | +Disable modules that are installed and enabled where For important information about module dependencies, see About enabling and disabling modules. |
+ No | +
| db_init_statements | +Advanced MySQL configuration parameter. Uses database initialization statements to run when connecting to the MySQL database. Consult a reference similar to this one before you set any values. | +No | +
About enabling and disabling modules
+{% include install/enable-disable-modules.html %} + +#### Related topics + +* Install the Magento software using the command line +* Enable and disable modules +* Command line installation + diff --git a/guides/v1.0/install-gde/install/install-cli-subcommands-enable.md b/guides/v1.0/install-gde/install/install-cli-subcommands-enable.md new file mode 100644 index 00000000000..684abe72ceb --- /dev/null +++ b/guides/v1.0/install-gde/install/install-cli-subcommands-enable.md @@ -0,0 +1,52 @@ +--- +layout: default +group: install +subgroup: T_Command-line installation +title: Enable and disable modules +menu_title: Enable and disable modules +menu_node: +menu_order: 5 +github_link: install-gde/install/install-cli-subcommands-enable.md +--- + + +#### Contents + +* Module enable, disable +* About enabling and disabling modules + + +Module enable, disable
+To enable or disable currently installed modules, use the following command: + + php index.php {module-enable|module-disable} {--modules="- "} [--force]
+
+Use the following command to list enabled and disabled modules:
+
+ php index.php help module-list
+
+For example, to disable the Weee module, enter:
+
+ php index.php module-disable --modules=Magento_Weee
+
+
- By default, the installer doesn't overwrite the Magento database if you install the Magento software in the same database instance. You can use the optional
clean_databaseparameter to change this behavior.
- - If you get errors during the installation, see Troubleshooting.
- The database server's fully qualified host name or IP address. -
localhostif your database serve is on the same host as your web server.
- - UNIX socket; for example,
/var/run/mysqld/mysqld.sock filesto store session data in the file system. File-based session storage is appropriate unless the Magento file system access is slow or you have a clustered database.
- db.filesto store session data in the database. Choose database storage if you have a clustered database; otherwise, there might not be much benefit over file-based storage.
+
+
+
+For important information about enabling and disabling modules, see About enabling and disabling modules.
+
+To enable or disable more than one module at a time, enter module names as a comma-separated list (no spaces).
+Update the database
+If you enabled one or more modules, run the following command to update the database: + + php index.php update + +About enabling and disabling modules
+{% include install/enable-disable-modules.html %} + +#### Related topics + +* Install the Magento software using the command line +* Get started with the command-line installation +* Create the deployment configuration, config.php +* Command line installation \ No newline at end of file diff --git a/guides/v1.0/install-gde/install/install-cli-subcommands.md b/guides/v1.0/install-gde/install/install-cli-subcommands.md new file mode 100644 index 00000000000..bac56071a20 --- /dev/null +++ b/guides/v1.0/install-gde/install/install-cli-subcommands.md @@ -0,0 +1,119 @@ +--- +layout: default +group: install +subgroup: T_Command-line installation +title: Get started with the command-line installation +menu_title: Get started with the command-line installation +menu_node: +menu_order: 1 +github_link: install-gde/install/install-cli-subcommands.md +--- + + +Contents
+ +See one of the following sections: + +* Before you start your installation +* First steps +* Command-line installer help commands +* Installing the Magento software using the command line +* Create the deployment configuration, config.php +* Enable and disable modules +* Maintenance mode +* Uninstall + +Before you start your installation
+{% include install/before-you-begin-cli.html %} + +The installer is designed to be run multiple times if necessary so you can: + +* Provide different values + + For example, after you configure your web server for Secure Sockets Layer (SSL), you can run the installer to set SSL options. + +* Correct mistakes in previous installations +* Install Magento in a different database instance + +First steps
+{% include install/first-steps-cli.html %} + +Command-line installer help commands
+To display a complete list of installer subcommands, enter: + + php index.php help + +To get help on a particular subcommand, enter: + + php index.php helpCommand line installer subcommands
+The following sections discuss the available subcommands. + +* Installing the Magento software using the command line +* Create the deployment configuration, config.php +* Enable and disable modules +* Update the database +* Maintenance mode +* Uninstall + +
+
+
+
+Not all subcommands are currently documented. Provide us input by editing this page on GitHub.
+Update the database
+To update the database (for example, after you install a new module or update an existing module), use the following command: + + php index.php update + +Maintenance mode
+Magento uses *maintenance mode* to disable bootstrapping; for example, if your system is being updated or reconfigured. + +Magento detects maintenance mode as follows: + +* If `var/.maintenance.flag` does not exist, maintenance mode is off and Magento operates normally. +* Otherwise, maintenance mode is on unless `var/.maintenance.ip` exists: + + `var/.maintenance.ip` can contain a list of comma-separated IP addresses. If an entry point is accessed using HTTP and the client IP address corresponds to one of the entries in that list, then maintenance mode is off. + +Command usage: + + php index.php maintenance [--set=1|0] [--addresses=- |none]
+
+
+
+
+
+
+For example, to enable maintenance mode:
+
+ php index.php maintenance --set=1
+
+To enable maintenance mode for all clients except 192.0.2.10:
+
+ php index.php maintenance --set=1 --addresses=192.0.2.10
+
+Running php index.php maintenance with no arguments displays the current status.
Uninstall
+The command discussed in this section does the following: + +* Drops and re-creates the database, if the connection settings are present in the deployment configuration (`app/etc/config.php`). All tables and data are lost because only database is re-created, not the tables. +* Deletes the contents of the `var` and `pub/static` directories, skipping paths that start with `.` (period). +* Deletes the deployment configuration, `app/etc/config.php` + +To perform the preceding tasks, enter the following command: + + php index.php uninstall + + +#### Related topics + +* Install the Magento software using the command line +* Enable and disable modules +* Create the deployment configuration, config.php +* Command line installation \ No newline at end of file diff --git a/guides/v1.0/install-gde/install/install-cli.md b/guides/v1.0/install-gde/install/install-cli.md index 60bb5a98ef8..0c357900143 100644 --- a/guides/v1.0/install-gde/install/install-cli.md +++ b/guides/v1.0/install-gde/install/install-cli.md @@ -1,11 +1,11 @@ --- layout: default group: install -subgroup: R_Installation -title: Install Magento software using the command line -menu_title: Install the Magento software using the command line -menu_node: -menu_order: 9 +subgroup: T_Command-line installation +title: Command line installation +menu_title: Command line installation +menu_node: parent +menu_order: 1 github_link: install-gde/install/install-cli.md --- @@ -16,329 +16,15 @@ See one of the following sections: * Before you start your installation * First steps -* Installing the Magento software from the command line -* Updating the Magento software -* Reinstalling the Magento softwareBefore you start your installation
+{% include install/before-you-begin-cli.html %} -Before you begin, make sure that: - -1. Your system meets the requirements discussed in Magento System Requirements. -2. You completed all prerequisite tasks discussed in Prerequisites. -3. You installed Composer and cloned the Magento GitHub repository as discussed in Install Composer and clone the Magento GitHub repository. -4. After you log in to the Magento server, switch to the web server user as discussed in Switching to the Apache user. - -
-
-
-
-The installer is designed to be run multiple times if necessary so you can:
-
-* Provide different values
-
- For example, after you configure your web server for Secure Sockets Layer (SSL), you can run the installer to set SSL options.
-* Correct mistakes in previous installations
-* Install Magento in a different database instance
-
-You must install Magento from its setup subdirectory.
-
-
First steps
+{% include install/first-steps-cli.html %} -Before you begin: - -1. Log in to the Magento server as, or switch to, the web server user. -2. Change to the following directory: - - cdExamples:
- - * Ubuntu: `cd /var/www/magento2/setup` - * CentOS: `cd /var/www/html/magento2/setup` - -3. Optionally run the following commands to find values for some required options: - -| Installer option | -Command | -
|---|---|
| Language | -php -f index.php help language |
-
| Time zone | -php -f index.php help timezone |
-
| Currency | -php -f index.php help currency |
-
-
-
-
-
-If an error displays when you run these commands, make sure you updated installation dependencies as discussed in Update installation dependencies.
-Installing the Magento software from the command line
- -The format of the install command follows: - - php -f index.php install --| Name | -Value | -Required? | -
|---|---|---|
| base_url | -Base URL to use to access your Magento Admin and storefront in the format Note: The scheme (
To access Magento on localhost, you can use either |
- Yes | -
| backend_frontname | -Path to access the Magento Admin. This path is appended to Base URL.
-For example, if Base URL is http://www.example.com and Admin Path is admin, the Admin Panel's URL is http://www.example.com/admin—provided you configured your web server for server rewrites. |
- Yes | -
| db_host | -Use any of the following: -Note: You can optionally specify the database server port in its host name like |
- Yes | -
| db_name | -Name of the Magento database instance in which you want to install the Magento database tables. | -Yes | -
| db_user | -User name of the Magento database instance owner. | -Yes | -
| db_pass | -Magento database instance owner's password. | -No | -
| db_prefix | -Use only if you're installing the Magento database tables in a database instance that has Magento tables in it already. -In that case, use a prefix to identify the Magento tables for this installation. Some customers have more than one Magento instance running on a server with all tables in the same database. -This option enables those customers to share the database server with more than one Magento installation. |
- No | -admin_firstname | -Magento administrator user's first name. | -Yes | - -
| admin_lastname | -Magento administrator user's last name. | -Yes | -
| admin_email | -Magento administrator user's e-mail address. | -Yes | -
| admin_username | -Magento administrator user name. | -Yes | -
| admin_password | -Magento administrator user password. | -Yes | -
| language | -Language code to use in the Admin and storefront. (If you have not done so already, you can view the list of language codes by entering php -f index.php help language from the setup directory.) |
- Yes | -
| currency | -Default currency to use in the storefront. (If you have not done so already, you can view the list of currencies by entering php -f index.php help currency from the setup directory.) |
- Yes | -
| timezone | -Default time zone to use in the Admin and storefront. (If you have not done so already, you can view the list of time zones by entering php -f index.php help timezone from the setup directory.) |
- Yes | -
| use_secure | -
|
- No | -
| base_secure_url | -
|
- No | -
| use_secure_admin | -
|
- No | -
| admin_use_security_key | -
|
- No | -
| session_save | -Use any of the following: - |
- No | -
| key | -If you have one, specify a key to encrypt sensitive data in the Magento database. (This includes passwords and personally identifiable customer information.) If you don't have one, Magento generates one for you. | -No | -
| use_sample_data | -
Sample data installs only if you already enabled the package as discussed in Enable optional Magento sample data . |
- No | -
| cleanup_database | -To drop database tables before installing the Magento software, specify this parameter without a value. Otherwise, the Magento database is left intact. | -No | -
| db_init_statements | -Advanced MySQL configuration parameter. Uses database initialization statements to run when connecting to the MySQL database. Consult a reference similar to this one before you set any values. | -No | -
| sales_order_increment_prefix | -Specify a string value to use as a prefix for sales orders. Typically, this is used to guarantee unique order numbers for payment processors. | -No | -
Sample localhost installation
- -The following example installs Magento with the following options: - -* The Magento software is installed in the `magento2` directory relative to the web server docroot on `localhost` and the path to the Magento Admin is `admin`; therefore: - - Your storefront URL is `http://localhost` and you can access the Magento Admin at `http://localhost/admin` - -* The database server is on the same host as the web server. - - The database name is `magento`, and the user name and password are both `magento` - -* Installs optional sample data - -* The Magento administrator has the following properties: - - * First and last name are is `Magento User` - * User name is `admin` and the password is `iamtheadmin` - * E-mail address is `user@example.com` - -* Default language is `en_US` (U.S. English) -* Default currency is U.S. dollars -* Default time zone is U.S. Central (America/Chicago) - - php -f index.php install --base_url=http://localhost/magento2/ \ - --backend_frontname=admin \ - --db_host=localhost --db_name=magento --db_user=magento --db_pass=magento \ - --admin_firstname=Magento --admin_lastname=User --admin_email=user@example.com \ - --admin_username=admin --admin_password=iamtheadmin --language=en_US \ - --currency=USD --timezone=America/Chicago - - -
-
-
-
-The command must be entered either on a single line or, as in the preceding example, with a \ character at the end of each line.
Updating the Magento software
-This section discusses how to update your Magento software without reinstalling it. To uninstall and reinstall, see the next section. - -You might do this in an development environment especially to get all the latest code changes. - -To update the Magento software: - -2. Log in to your Magento server as a user with permissions to modify files in the Magento file system (for example, the web server user). -3. Enter the following commands in the order shown: - - cdReinstalling the Magento software
-This section discusses how to uninstall and then reinstall the Magento software. - -To reinstall the Magento software: - -2. Log in to your Magento server as a user with permissions to modify files in the Magento file system (for example, the web server user). -3. Enter the following commands in the order shown: - - cdComposer and Magento
+ +We now use Composer to install the Magento software. Composer enables us to manage the Magento system, extensions, and their dependencies. + +Composer provides you with the following advantages: + +* Enables you to reuse third-party libraries without bundling them with source code +* Component-based architecture with robust dependency management +* Manages dependencies to reduce extension conflicts and compatibility issues +* Versioned dependencies +* Semantic versioning +* Supports PHP Framework Interoperability standard + +We'll have more information soon on how developers can use Composer to package extensions to distribute to Magento merchants and to other developers. + +Steps to install Magento
+ +To install Magento, complete the following tasks in the order shown: + +1. Magento system requirements +1. Prerequisites +1. Install Composer and clone the Magento repository +1. Update installation dependencies +1. Install the Magento software: + * Setup Wizard installation + * Command line installation +1. Verify the installation + +If you have issues installing the Magento software, see Troubleshooting suggestions + +#### Next step + +Continue with Install Composer and clone the Magento repository + diff --git a/guides/v1.0/install-gde/install/prepare-install.md b/guides/v1.0/install-gde/install/prepare-install.md index b367dad78e2..eac22173889 100644 --- a/guides/v1.0/install-gde/install/prepare-install.md +++ b/guides/v1.0/install-gde/install/prepare-install.md @@ -1,11 +1,11 @@ --- layout: default group: install -subgroup: R_Installation +subgroup: Q_Pre-installation title: Update installation dependencies menu_title: Update installation dependencies menu_node: -menu_order: 6 +menu_order: 5 github_link: install-gde/install/prepare-install.md --- @@ -31,18 +31,17 @@ To switch to the web server user on Ubuntu: 1. Enter the following command: -su www-data+ su www-data 2. If a password prompt displays but you don't know the user's password, continue with the next step; otherwise, continue with Running Composer to update dependencies. 3. To enable the `www-data` user's shell and to set a password, enter the following commands in the order shown: -
sudo chsh -s /bin/bash www-data - sudo passwd www-data+ sudo chsh -s /bin/bash www-data && sudo passwd www-data 4. Run the following command again and enter the user's password: -
su www-data+ su www-data 5. Continue with Running Composer to update dependencies. @@ -52,19 +51,19 @@ To switch to the web server user on CentOS: 1. Enter the following command: -
su - apache+ su - apache If the following error displays, continue with the next step; otherwise, continue with Running Composer to update dependencies. -
This account is currently not available.+ This account is currently not available. 2. To give `apache` a valid shell account so you can switch to it, enter the following command: -
sudo chsh -s /bin/bash apache+ sudo chsh -s /bin/bash apache 3. Run the following command again; this time, it should work: -
su - apache+ su - apache 3. Continue with the next section. @@ -73,11 +72,9 @@ To switch to the web server user on CentOS: After you completed the tasks discussed in the preceding section, update dependencies as follows: 1. Log in to your Magento server as the web server user or switch to that user. -2. Change to the Magento installation directory. For example, +2. Change to the Magento installation directory and run `composer install`. For example, - `cd /var/www/html/magento2` - -3. As user with privileges to write to the web server docroot, enter `composer install` + cd /var/www/html/magento2 && composer install This command updates package dependencies and can take a few minutes to complete. diff --git a/guides/v1.0/install-gde/install/sample-data.md b/guides/v1.0/install-gde/install/sample-data.md index edd02f8dd83..5a3271506ae 100644 --- a/guides/v1.0/install-gde/install/sample-data.md +++ b/guides/v1.0/install-gde/install/sample-data.md @@ -8,7 +8,7 @@ menu_node: parent menu_order: 1 github_link: install-gde/install/sample-data.md --- - + #### Contents * Introduction to Magento sample data @@ -49,21 +49,21 @@ To update `composer.json`: 3. Enter the following command to require the current version of the sample data and media packages: - composer require magento/sample-data:
PHP 5.6 on Ubuntu 12
Before continuing, enter the following command to make sure you're running Apache 2.4: diff --git a/guides/v1.0/install-gde/trouble/tshoot.md b/guides/v1.0/install-gde/trouble/tshoot.md index d0b9511e956..202e3db7c01 100644 --- a/guides/v1.0/install-gde/trouble/tshoot.md +++ b/guides/v1.0/install-gde/trouble/tshoot.md @@ -11,12 +11,15 @@ github_link: install-gde/trouble/tshoot.md The following topics discuss the installation errors and suggested solutions: +* You cannot access the Magento software in a web browser +* Error after logging in to the Magento Admin +* After installing, images and stylesheets do not load; only text displays, no graphics. * The PHP mcrypt extension is not installed properly * Installation dependencies not met * Cannot clone the Magento GitHub repository -* Cannot run 'composer install' +* Cannot runcomposer install
+* When running composer install or composer update, see error enter your GitHub credentials to go over the API rate limit
* During installation, PHP date warning
* During installation, fatal PDO error displays
-* You Cannot access Magento software in a web browser
-* Error after logging in to the Magento Admin
-* After installing, images and stylesheets do not load; only text displays, no graphics.
+* Installation fails; cannot create install.log
+
diff --git a/guides/v1.0/install-gde/trouble/tshoot_access-browser.md b/guides/v1.0/install-gde/trouble/tshoot_access-browser.md
index d0896c45e86..8a572d19753 100644
--- a/guides/v1.0/install-gde/trouble/tshoot_access-browser.md
+++ b/guides/v1.0/install-gde/trouble/tshoot_access-browser.md
@@ -5,7 +5,7 @@ subgroup: Z_Troubleshooting
title: Cannot access Magento software in a web browser
menu_title: Cannot access Magento software in a web browser
menu_node:
-menu_order: 7
+menu_order: 2
github_link: install-gde/install/composer-clone.md
---
diff --git a/guides/v1.0/install-gde/trouble/tshoot_admin.md b/guides/v1.0/install-gde/trouble/tshoot_admin.md
index fc6a524de06..e352ac0a242 100644
--- a/guides/v1.0/install-gde/trouble/tshoot_admin.md
+++ b/guides/v1.0/install-gde/trouble/tshoot_admin.md
@@ -5,7 +5,7 @@ subgroup: Z_Troubleshooting
title: Error after logging in to the Magento Admin
menu_title: Error after logging in to the Magento Admin
menu_node:
-menu_order: 8
+menu_order: 5
github_link: install-gde/install/composer-clone.md
---
diff --git a/guides/v1.0/install-gde/trouble/tshoot_clone.md b/guides/v1.0/install-gde/trouble/tshoot_clone.md
index 1b1d8392654..a64111e1b4a 100644
--- a/guides/v1.0/install-gde/trouble/tshoot_clone.md
+++ b/guides/v1.0/install-gde/trouble/tshoot_clone.md
@@ -5,7 +5,7 @@ subgroup: Z_Troubleshooting
title: Cannot clone the Magento GitHub repository
menu_title: Cannot clone the Magento GitHub repository
menu_node:
-menu_order: 3
+menu_order: 15
github_link: install-gde/trouble/tshoot_clone.md
---
diff --git a/guides/v1.0/install-gde/trouble/tshoot_composer-install.md b/guides/v1.0/install-gde/trouble/tshoot_composer-install.md
index 7350c69c852..5b3a3d559d7 100644
--- a/guides/v1.0/install-gde/trouble/tshoot_composer-install.md
+++ b/guides/v1.0/install-gde/trouble/tshoot_composer-install.md
@@ -5,7 +5,7 @@ subgroup: Z_Troubleshooting
title: Cannot run 'composer install'
menu_title: Cannot run 'composer install'
menu_node:
-menu_order: 4
+menu_order: 7
github_link: install-gde/trouble/tshoot_composer-install.md
---
diff --git a/guides/v1.0/install-gde/trouble/tshoot_install-log.md b/guides/v1.0/install-gde/trouble/tshoot_install-log.md
index 6f0c8b140e8..90bdaf9e78a 100644
--- a/guides/v1.0/install-gde/trouble/tshoot_install-log.md
+++ b/guides/v1.0/install-gde/trouble/tshoot_install-log.md
@@ -5,7 +5,7 @@ subgroup: Z_Troubleshooting
title: Installation fails; cannot create install.log
menu_title: Installation fails; cannot create install.log
menu_node:
-menu_order: 20
+menu_order: 400
github_link: install-gde/trouble/tshoot_install-log.md
---
diff --git a/guides/v1.0/install-gde/trouble/tshoot_install_depend.md b/guides/v1.0/install-gde/trouble/tshoot_install_depend.md
index ef8e81b403f..9a42b938147 100644
--- a/guides/v1.0/install-gde/trouble/tshoot_install_depend.md
+++ b/guides/v1.0/install-gde/trouble/tshoot_install_depend.md
@@ -5,7 +5,7 @@ subgroup: Z_Troubleshooting
title: Installation dependencies not met
menu_title: Installation dependencies not met
menu_node:
-menu_order: 2
+menu_order: 10
github_link: install-gde/trouble/tshoot_install_depend.md
---
diff --git a/guides/v1.0/install-gde/trouble/tshoot_mcrypt.md b/guides/v1.0/install-gde/trouble/tshoot_mcrypt.md
index a5c704f75fa..9d2eb016385 100644
--- a/guides/v1.0/install-gde/trouble/tshoot_mcrypt.md
+++ b/guides/v1.0/install-gde/trouble/tshoot_mcrypt.md
@@ -5,7 +5,7 @@ subgroup: Z_Troubleshooting
title: The PHP mcrypt extension is not installed properly
menu_title: The PHP mcrypt extension is not installed properly
menu_node:
-menu_order: 1
+menu_order: 22
github_link: install-gde/trouble/tshoot_mcrypt.md
---
diff --git a/guides/v1.0/install-gde/trouble/tshoot_mod_access_compat.md b/guides/v1.0/install-gde/trouble/tshoot_mod_access_compat.md
new file mode 100644
index 00000000000..9252dad9543
--- /dev/null
+++ b/guides/v1.0/install-gde/trouble/tshoot_mod_access_compat.md
@@ -0,0 +1,42 @@
+---
+layout: default
+group: install
+subgroup: Z_Troubleshooting
+title: 503 (Service Unavailable) errors accessing Magento software in a web browser
+menu_title: 503 (Service Unavailable) errors accessing Magento software in a web browser
+menu_node:
+menu_order: 3
+github_link: install-gde/trouble/mod_access_compat.md
+---
+
+
+503 (Service Unavailable) errors accessing Magento software in a web browser
+ +#### Symptoms + +When you try to access your Magento Admin or storefront in a web browser, you get HTTP 503 (Service Unavailable) errors. + +To confirm this issue is not related to maintenance mode, look in your Apache `error.log` for messages that include: + + "Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration". + +#### Details + +Apache 2.4 changes the way certain directives related to `.htaccess` work. The Magento software uses `.htaccess` to rewrite URLs. If `.htaccess` doesn't work properly, you cannot access the Magento software in a web browser. + +Not all Apache 2.4 distributions have this issue because in some cases, a compatibility module named `mod_access_compat` is enabled by default. If, however, your Apache 2.4 distribution has this module disabled, you must perform the tasks discussed in the next section. You can also consult the resources listed in the final section in this topic. + +#### Suggested solution +As a user with 'root' privileges, enter the following commands: + + a2enmod access_compat + serviceIf the command fails, try making the web server user the owner of your web server docroot directory.
-For example, on Ubuntu, enter sudo chown www-data /var/www.
For example, on Ubuntu, enter sudo chown www-data /var/www