{"action":"created","comment":{"url":"https://api.github.com/repos/akeneo/pim-docs/pulls/comments/35305715","id":35305715,"diff_hunk":"@@ -4,96 +4,236 @@ How to Update Products\n Prerequisites\n -------------\n \n-The Akeneo PIM project introduces services to help you manage your product entities.\n+The Akeneo PIM project introduces services to help you to manage your product objects.\n \n-The product updater allows to set values for many products, or copy a value to another value in many products\n+As the product model is the main object of the application, the use cases are more advanced than for simple models,\n \n-In the following examples, we will assume that we have a collection of one or many products in the variable\n-``$products``. The collection can be fetched from the database or newly created with the\n-``pim_catalog.builder.product`` service.\n+* a set of property updates on a single product (case of Product Edit Form)\n+* a different set of property updates on many products (case of Product Import)\n+* a similar set of property updates on many products (case of Bulk Action)\n+* [put your own logic here]\n \n-.. note::\n+We provide different services to allow you to assemble your custom \"update logic\".\n+\n+The default case is covered by the use of an ObjectUpdaterInterface to apply a set of property updates on a product.\n+\n+You'll find also some services to update a single doctrine field data or an attribute data of a product (we hide this implementation detail, attribute vs doctrine field, under the term 'property').\n \n-   The updater does not validate and persist the products in the database, these operations are detailed in specific chapters\n+There are four services to handle this, a PropertySetterInterface, a PropertyAdderInterface, a PropertyRemoverInterface and a PropertyCopierInterface.\n \n-Instantiate a new updater\n--------------------------\n+Instantiate a New ObjectUpdaterInterface\n+----------------------------------------\n \n-The product updater is a service, you can fetch it from the container.\n+The product updater ``Pim\\Component\\Catalog\\Updater\\ProductUpdater`` implements the ``Akeneo\\Component\\StorageUtils\\Updater\\ObjectUpdaterInterface``.\n+\n+The product updater is available has a service, you can fetch it from the container.\n \n .. code-block:: php\n \n     $updater = $this->getContainer()->get('pim_catalog.updater.product');\n \n-Use setters and copiers\n------------------------\n+.. note::\n+\n+    We provide several services which implements `ObjectUpdaterInterface` to manipulate other business models (family, attribute, etc).\n+\n+.. warning::\n+\n+   The updater does not validate and save the products in the database, these operations are done by the Validator and the Saver (detailed in specific chapters).\n+\n+   We target to respect the Single Responsibility Principle (SRP) in our classes, feel free to use these different services through a `Facade` if it ease your developments.\n+\n+Use the Object Updater\n+----------------------\n+\n+Then we can apply many property updates on a product.\n+\n+.. code-block:: php\n+\n+    $fieldUpdates = [\n+        \"sku\": [[\"locale\": null, \"scope\":  null, \"data\":  \"MySku\"]],\n+        \"description\": [[\"locale\": \"en_US\", \"scope\": \"mobile\", \"data\": \"My description\"]]\n+        \"categories\": [\"tshirt\", \"promo\"],\n+    ];\n+    $this->updater->update($product, $fieldUpdates);\n+\n+.. note::\n+\n+    The standard array format used for property updates can be obtained by normalizing product values like this,\n+    \"$container->get('pim_serializer')->normalize($values, 'json', ['entity' => 'product'])\".\n+\n+Instanciate a New PropertySetterInterface\n+-----------------------------------------\n+\n+The product property setter implements the ``Akeneo\\Component\\StorageUtils\\Updater\\PropertySetterInterface``.\n+\n+It's available has a service, you can fetch it from the container.\n+\n+.. code-block:: php\n+\n+    $propertySetter = $this->getContainer()->get('pim_catalog.updater.product_property_setter');\n+\n+Use the PropertySetterInterface\n+-------------------------------\n+\n+The property setter allows to set a single property (doctrine field data or attribute data).\n+\n+The property setter replace the data if it already exists.\n+\n+.. code-block:: php\n+\n+    // sets a data in the product name (an attribute)\n+    $propertySetter->setData($product, 'name', 'my name');\n+\n+    // sets a data in the product name (a field)\n+    $propertySetter->setData($product, 'categories', ['category_code1', 'category_code2']);\n+\n+    // sets a localizable and scopable product attribute data\n+    $propertySetter->setData($product, 'description', 'my description', ['locale' => 'en_US', 'scope' => 'mobile']);\n+\n+.. note::\n+\n+    This service has been reworked since the 1.3 to add the support of doctrine fields, become more complete and consistent with other property updaters.\n+\n+    The method 'ProductUpdater::setValue()' is now deprecated, you should use the `PropertySetterInterface::setData()`.\n+\n+Instanciate a New PropertyAdderInterface\n+-----------------------------------------\n+\n+The product property adder implements the ``Akeneo\\Component\\StorageUtils\\Updater\\PropertyAdderInterface``.\n+\n+It's available has a service, you can fetch it from the container.\n+\n+.. code-block:: php\n+\n+    $propertyAdder = $this->getContainer()->get('pim_catalog.updater.product_property_adder');\n \n-Setters\n--------\n+Use the PropertyAdderInterface\n+------------------------------\n \n-In order to use setters you will need to use the 'setValue()' method. The first argument matches all the products\n-you want to set a new value, the second argument is the attribute code, the third argument is the value to set (it\n-has to be compliant with the attribute type). Then you can specify the locale and the scope (locale and scope must be\n-used when the attribute is localizable or scopable).\n+The property adder allows to add an item in a single property (doctrine field data or attribute data) which contain a collection.\n+\n+This one is only available for properties that contains many items (as categories, options, prices).\n+\n+The property adder keep the existing items and add a new item inside.\n \n .. code-block:: php\n \n-    $updater\n-        ->setValue($products, 'name', 'Akeneo T-Shirt (new)')\n-        ->setValue($products, 'description', 'Akeneo T-Shirt white with short sleeve (new)', 'en_US', 'ecommerce')\n-        ->setValue($products, 'price', [['data' => 101.2, 'currency' => 'USD']], 'en_US', 'mobile');\n+    // adds a data in the product color (a multiselect attribute)","path":"cookbook/product/update-product.rst","position":140,"original_position":140,"commit_id":"6a4cc32efe5d61875c01bce2813c43660b264240","original_commit_id":"6a4cc32efe5d61875c01bce2813c43660b264240","user":{"login":"jjanvier","id":3691804,"avatar_url":"https://avatars.githubusercontent.com/u/3691804?v=3","gravatar_id":"","url":"https://api.github.com/users/jjanvier","html_url":"https://github.com/jjanvier","followers_url":"https://api.github.com/users/jjanvier/followers","following_url":"https://api.github.com/users/jjanvier/following{/other_user}","gists_url":"https://api.github.com/users/jjanvier/gists{/gist_id}","starred_url":"https://api.github.com/users/jjanvier/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jjanvier/subscriptions","organizations_url":"https://api.github.com/users/jjanvier/orgs","repos_url":"https://api.github.com/users/jjanvier/repos","events_url":"https://api.github.com/users/jjanvier/events{/privacy}","received_events_url":"https://api.github.com/users/jjanvier/received_events","type":"User","site_admin":false},"body":"adds data","created_at":"2015-07-23T09:48:28Z","updated_at":"2015-07-23T09:48:28Z","html_url":"https://github.com/akeneo/pim-docs/pull/104#discussion_r35305715","pull_request_url":"https://api.github.com/repos/akeneo/pim-docs/pulls/104","_links":{"self":{"href":"https://api.github.com/repos/akeneo/pim-docs/pulls/comments/35305715"},"html":{"href":"https://github.com/akeneo/pim-docs/pull/104#discussion_r35305715"},"pull_request":{"href":"https://api.github.com/repos/akeneo/pim-docs/pulls/104"}}},"pull_request":{"url":"https://api.github.com/repos/akeneo/pim-docs/pulls/104","id":40650027,"html_url":"https://github.com/akeneo/pim-docs/pull/104","diff_url":"https://github.com/akeneo/pim-docs/pull/104.diff","patch_url":"https://github.com/akeneo/pim-docs/pull/104.patch","issue_url":"https://api.github.com/repos/akeneo/pim-docs/issues/104","number":104,"state":"open","locked":false,"title":"Document the updater api + enhance query, validate and save product chapters","user":{"login":"nidup","id":2104359,"avatar_url":"https://avatars.githubusercontent.com/u/2104359?v=3","gravatar_id":"","url":"https://api.github.com/users/nidup","html_url":"https://github.com/nidup","followers_url":"https://api.github.com/users/nidup/followers","following_url":"https://api.github.com/users/nidup/following{/other_user}","gists_url":"https://api.github.com/users/nidup/gists{/gist_id}","starred_url":"https://api.github.com/users/nidup/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nidup/subscriptions","organizations_url":"https://api.github.com/users/nidup/orgs","repos_url":"https://api.github.com/users/nidup/repos","events_url":"https://api.github.com/users/nidup/events{/privacy}","received_events_url":"https://api.github.com/users/nidup/received_events","type":"User","site_admin":false},"body":"","created_at":"2015-07-23T08:57:11Z","updated_at":"2015-07-23T09:48:28Z","closed_at":null,"merged_at":null,"merge_commit_sha":"a28664b9eea79e6606dc47cfed9d274b010eff85","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/akeneo/pim-docs/pulls/104/commits","review_comments_url":"https://api.github.com/repos/akeneo/pim-docs/pulls/104/comments","review_comment_url":"https://api.github.com/repos/akeneo/pim-docs/pulls/comments{/number}","comments_url":"https://api.github.com/repos/akeneo/pim-docs/issues/104/comments","statuses_url":"https://api.github.com/repos/akeneo/pim-docs/statuses/6a4cc32efe5d61875c01bce2813c43660b264240","head":{"label":"akeneo:updater-api","ref":"updater-api","sha":"6a4cc32efe5d61875c01bce2813c43660b264240","user":{"login":"akeneo","id":2510186,"avatar_url":"https://avatars.githubusercontent.com/u/2510186?v=3","gravatar_id":"","url":"https://api.github.com/users/akeneo","html_url":"https://github.com/akeneo","followers_url":"https://api.github.com/users/akeneo/followers","following_url":"https://api.github.com/users/akeneo/following{/other_user}","gists_url":"https://api.github.com/users/akeneo/gists{/gist_id}","starred_url":"https://api.github.com/users/akeneo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/akeneo/subscriptions","organizations_url":"https://api.github.com/users/akeneo/orgs","repos_url":"https://api.github.com/users/akeneo/repos","events_url":"https://api.github.com/users/akeneo/events{/privacy}","received_events_url":"https://api.github.com/users/akeneo/received_events","type":"Organization","site_admin":false},"repo":{"id":12193604,"name":"pim-docs","full_name":"akeneo/pim-docs","owner":{"login":"akeneo","id":2510186,"avatar_url":"https://avatars.githubusercontent.com/u/2510186?v=3","gravatar_id":"","url":"https://api.github.com/users/akeneo","html_url":"https://github.com/akeneo","followers_url":"https://api.github.com/users/akeneo/followers","following_url":"https://api.github.com/users/akeneo/following{/other_user}","gists_url":"https://api.github.com/users/akeneo/gists{/gist_id}","starred_url":"https://api.github.com/users/akeneo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/akeneo/subscriptions","organizations_url":"https://api.github.com/users/akeneo/orgs","repos_url":"https://api.github.com/users/akeneo/repos","events_url":"https://api.github.com/users/akeneo/events{/privacy}","received_events_url":"https://api.github.com/users/akeneo/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/akeneo/pim-docs","description":"Akeneo PIM documentation","fork":false,"url":"https://api.github.com/repos/akeneo/pim-docs","forks_url":"https://api.github.com/repos/akeneo/pim-docs/forks","keys_url":"https://api.github.com/repos/akeneo/pim-docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/akeneo/pim-docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/akeneo/pim-docs/teams","hooks_url":"https://api.github.com/repos/akeneo/pim-docs/hooks","issue_events_url":"https://api.github.com/repos/akeneo/pim-docs/issues/events{/number}","events_url":"https://api.github.com/repos/akeneo/pim-docs/events","assignees_url":"https://api.github.com/repos/akeneo/pim-docs/assignees{/user}","branches_url":"https://api.github.com/repos/akeneo/pim-docs/branches{/branch}","tags_url":"https://api.github.com/repos/akeneo/pim-docs/tags","blobs_url":"https://api.github.com/repos/akeneo/pim-docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/akeneo/pim-docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/akeneo/pim-docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/akeneo/pim-docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/akeneo/pim-docs/statuses/{sha}","languages_url":"https://api.github.com/repos/akeneo/pim-docs/languages","stargazers_url":"https://api.github.com/repos/akeneo/pim-docs/stargazers","contributors_url":"https://api.github.com/repos/akeneo/pim-docs/contributors","subscribers_url":"https://api.github.com/repos/akeneo/pim-docs/subscribers","subscription_url":"https://api.github.com/repos/akeneo/pim-docs/subscription","commits_url":"https://api.github.com/repos/akeneo/pim-docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/akeneo/pim-docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/akeneo/pim-docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/akeneo/pim-docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/akeneo/pim-docs/contents/{+path}","compare_url":"https://api.github.com/repos/akeneo/pim-docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/akeneo/pim-docs/merges","archive_url":"https://api.github.com/repos/akeneo/pim-docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/akeneo/pim-docs/downloads","issues_url":"https://api.github.com/repos/akeneo/pim-docs/issues{/number}","pulls_url":"https://api.github.com/repos/akeneo/pim-docs/pulls{/number}","milestones_url":"https://api.github.com/repos/akeneo/pim-docs/milestones{/number}","notifications_url":"https://api.github.com/repos/akeneo/pim-docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/akeneo/pim-docs/labels{/name}","releases_url":"https://api.github.com/repos/akeneo/pim-docs/releases{/id}","created_at":"2013-08-18T10:17:30Z","updated_at":"2015-04-29T14:41:33Z","pushed_at":"2015-07-23T08:57:11Z","git_url":"git://github.com/akeneo/pim-docs.git","ssh_url":"git@github.com:akeneo/pim-docs.git","clone_url":"https://github.com/akeneo/pim-docs.git","svn_url":"https://github.com/akeneo/pim-docs","homepage":"","size":3087,"stargazers_count":12,"watchers_count":12,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":24,"mirror_url":null,"open_issues_count":6,"forks":24,"open_issues":6,"watchers":12,"default_branch":"master"}},"base":{"label":"akeneo:master","ref":"master","sha":"4a31cee134a616692830e7b3f78625120f15bcd3","user":{"login":"akeneo","id":2510186,"avatar_url":"https://avatars.githubusercontent.com/u/2510186?v=3","gravatar_id":"","url":"https://api.github.com/users/akeneo","html_url":"https://github.com/akeneo","followers_url":"https://api.github.com/users/akeneo/followers","following_url":"https://api.github.com/users/akeneo/following{/other_user}","gists_url":"https://api.github.com/users/akeneo/gists{/gist_id}","starred_url":"https://api.github.com/users/akeneo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/akeneo/subscriptions","organizations_url":"https://api.github.com/users/akeneo/orgs","repos_url":"https://api.github.com/users/akeneo/repos","events_url":"https://api.github.com/users/akeneo/events{/privacy}","received_events_url":"https://api.github.com/users/akeneo/received_events","type":"Organization","site_admin":false},"repo":{"id":12193604,"name":"pim-docs","full_name":"akeneo/pim-docs","owner":{"login":"akeneo","id":2510186,"avatar_url":"https://avatars.githubusercontent.com/u/2510186?v=3","gravatar_id":"","url":"https://api.github.com/users/akeneo","html_url":"https://github.com/akeneo","followers_url":"https://api.github.com/users/akeneo/followers","following_url":"https://api.github.com/users/akeneo/following{/other_user}","gists_url":"https://api.github.com/users/akeneo/gists{/gist_id}","starred_url":"https://api.github.com/users/akeneo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/akeneo/subscriptions","organizations_url":"https://api.github.com/users/akeneo/orgs","repos_url":"https://api.github.com/users/akeneo/repos","events_url":"https://api.github.com/users/akeneo/events{/privacy}","received_events_url":"https://api.github.com/users/akeneo/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/akeneo/pim-docs","description":"Akeneo PIM documentation","fork":false,"url":"https://api.github.com/repos/akeneo/pim-docs","forks_url":"https://api.github.com/repos/akeneo/pim-docs/forks","keys_url":"https://api.github.com/repos/akeneo/pim-docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/akeneo/pim-docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/akeneo/pim-docs/teams","hooks_url":"https://api.github.com/repos/akeneo/pim-docs/hooks","issue_events_url":"https://api.github.com/repos/akeneo/pim-docs/issues/events{/number}","events_url":"https://api.github.com/repos/akeneo/pim-docs/events","assignees_url":"https://api.github.com/repos/akeneo/pim-docs/assignees{/user}","branches_url":"https://api.github.com/repos/akeneo/pim-docs/branches{/branch}","tags_url":"https://api.github.com/repos/akeneo/pim-docs/tags","blobs_url":"https://api.github.com/repos/akeneo/pim-docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/akeneo/pim-docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/akeneo/pim-docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/akeneo/pim-docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/akeneo/pim-docs/statuses/{sha}","languages_url":"https://api.github.com/repos/akeneo/pim-docs/languages","stargazers_url":"https://api.github.com/repos/akeneo/pim-docs/stargazers","contributors_url":"https://api.github.com/repos/akeneo/pim-docs/contributors","subscribers_url":"https://api.github.com/repos/akeneo/pim-docs/subscribers","subscription_url":"https://api.github.com/repos/akeneo/pim-docs/subscription","commits_url":"https://api.github.com/repos/akeneo/pim-docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/akeneo/pim-docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/akeneo/pim-docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/akeneo/pim-docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/akeneo/pim-docs/contents/{+path}","compare_url":"https://api.github.com/repos/akeneo/pim-docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/akeneo/pim-docs/merges","archive_url":"https://api.github.com/repos/akeneo/pim-docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/akeneo/pim-docs/downloads","issues_url":"https://api.github.com/repos/akeneo/pim-docs/issues{/number}","pulls_url":"https://api.github.com/repos/akeneo/pim-docs/pulls{/number}","milestones_url":"https://api.github.com/repos/akeneo/pim-docs/milestones{/number}","notifications_url":"https://api.github.com/repos/akeneo/pim-docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/akeneo/pim-docs/labels{/name}","releases_url":"https://api.github.com/repos/akeneo/pim-docs/releases{/id}","created_at":"2013-08-18T10:17:30Z","updated_at":"2015-04-29T14:41:33Z","pushed_at":"2015-07-23T08:57:11Z","git_url":"git://github.com/akeneo/pim-docs.git","ssh_url":"git@github.com:akeneo/pim-docs.git","clone_url":"https://github.com/akeneo/pim-docs.git","svn_url":"https://github.com/akeneo/pim-docs","homepage":"","size":3087,"stargazers_count":12,"watchers_count":12,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":24,"mirror_url":null,"open_issues_count":6,"forks":24,"open_issues":6,"watchers":12,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/akeneo/pim-docs/pulls/104"},"html":{"href":"https://github.com/akeneo/pim-docs/pull/104"},"issue":{"href":"https://api.github.com/repos/akeneo/pim-docs/issues/104"},"comments":{"href":"https://api.github.com/repos/akeneo/pim-docs/issues/104/comments"},"review_comments":{"href":"https://api.github.com/repos/akeneo/pim-docs/pulls/104/comments"},"review_comment":{"href":"https://api.github.com/repos/akeneo/pim-docs/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/akeneo/pim-docs/pulls/104/commits"},"statuses":{"href":"https://api.github.com/repos/akeneo/pim-docs/statuses/6a4cc32efe5d61875c01bce2813c43660b264240"}}}}