DOCs: update (#4349)

* Updated docs * Update README.md Co-authored-by: Colin Mollenhour <[email protected]> * rtd * ignore CNAME in composer install * added git label * added blog posts (releases) * added blog posts (others) * spaces [ski ci] * removed blog posts * Updated modules section - step1: https://github.com/fballiano/awesome-openmage * internal links * minor title * minor change * link to DDEV windows guide --------- Co-authored-by: Colin Mollenhour <[email protected]>
OpenMage · Nov 30, 2024 · 4103e06 · 4103e06
1 parent e47aa19
commit 4103e06
Show file tree

Hide file tree

Showing 77 changed files with 1,803 additions and 571 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -21,6 +21,8 @@
 /.phpstan.dist.neon export-ignore
 /.rector.php export-ignore
 
+/CNAME export-ignore
+
 /README.md export-ignore
 
 # Enforce checkout with linux lf consistent over all platforms

diff --git a/.github/labeler.yml b/.github/labeler.yml
@@ -5,6 +5,13 @@
       .github/**/*
     ]
 
+'git':
+  - changed-files:
+    - any-glob-to-any-file: [
+      .gitattributes,
+      .gitignore
+    ]
+
 'htaccess':
   - changed-files:
     - any-glob-to-any-file: [

diff --git a/README.md b/README.md
diff --git a/docs/content/api/rest/resources/customers.md b/docs/content/api/rest/resources/customers.md
@@ -1,21 +1,6 @@
-\--- layout: v1x\_rest title: Customers --- JSON responses on this page contributed by Tim Reynolds
+# Customers
 
-*   [REST API: Customers](#RESTAPI-Resource-Customers-RESTAPI-Customers)
-    *   [URI: /customers](#RESTAPI-Resource-Customers-URI--customers)
-        *   [HTTP Method: GET /customers](#RESTAPI-Resource-Customers-HTTPMethod-GET-customers)
-        *   [HTTP Method: POST /customers](#RESTAPI-Resource-Customers-HTTPMethod-POST-customers)
-        *   [HTTP Method: PUT /customers](#RESTAPI-Resource-Customers-HTTPMethod-PUT-customers)
-        *   [HTTP Method: DELETE /customers](#RESTAPI-Resource-Customers-HTTPMethod-DELETE-customers)
-*   [REST API: Customer](#RESTAPI-Resource-Customers-RESTAPI-Customer)
-    *   [URI: /customers/:customerId](#RESTAPI-Resource-Customers-URI--customers--customerId)
-        *   [HTTP Method: GET /customers/:customerId](#RESTAPI-Resource-Customers-HTTPMethod-GET-customers--customerId)
-        *   [HTTP Method: POST /customers/:customerId](#RESTAPI-Resource-Customers-HTTPMethod-POST-customers--customerId)
-        *   [HTTP Method: PUT /customers/:customerId](#RESTAPI-Resource-Customers-HTTPMethod-PUT-customers--customerId)
-        *   [HTTP Method: DELETE /customers/:customerId](#RESTAPI-Resource-Customers-HTTPMethod-DELETE-customers--customerId)
-
-## Customers
-
-#### URI: /customers
+## URI: /customers
 
 Allows you to create and retrieve customers.
 
@@ -164,9 +149,7 @@ If the customer was created successfully, we receive **Response HTTP Code** = 20
 
 **Description**: Not allowed
 
-## Customer
-
-#### URI: /customers/:customerId
+## URI: /customers/:customerId
 
 Allows you to manage existing customers.
 
@@ -187,40 +170,39 @@ Allows you to manage existing customers.
     GET http://om.ddev.site/api/rest/customers/2
     ```
 
-**Response Body**:
+**Response body: XML**
 
+```xml
 <?xml version="1.0"?>
-<magento\_api>
-<entity\_id>2</entity\_id>
-<website\_id>1</website\_id>
-<email>[email protected]</email>
-<group\_id>1</group\_id>
-<created\_at>2012-03-22 14:15:54</created\_at>
-<disable\_auto\_group\_change>1</disable\_auto\_group\_change>
-<created\_in>Default Store View</created\_in>
-<firstname>john</firstname>
-<lastname>Doe</lastname>
-<last\_logged\_in>2012-03-22 14:15:56</last\_logged\_in>
-</magento\_api>
-
-**response example: json**
-
-get [http://om.ddev.site/api/rest/customers/141](http://om.ddev.site/api/rest/customers)
+<magento_api>
+    <entity_id>2</entity_id>
+    <website_id>1</website_id>
+    <email>[email protected]</email>
+    <group_id>1</group_id>
+    <created_at>2012-03-22 14:15:54</created_at>
+    <disable_auto_group_change>1</disable_auto_group_change>
+    <created_in>Default Store View</created_in>
+    <firstname>john</firstname>
+    <lastname>Doe</lastname>
+    <last_logged_in>2012-03-22 14:15:56</last_logged_in>
+</magento_api>
+```
 
-**response body**:
+**Response body: JSON**
 
+```json
 {
-"entity\_id": "2",
-"website\_id": "1",
-"email": "[email protected]",
-"group\_id": "1",
-"created\_at": "2012-03-22 14:15:54",
-"disable\_auto\_group\_change": "1",
-"created\_in": "English",
-"firstname": "john",
-"lastname": "Doe"
+    "entity_id": "2",
+    "website_id": "1",
+    "email": "[email protected]",
+    "group_id": "1",
+    "created_at": "2012-03-22 14:15:54",
+    "disable_auto_group_change": "1",
+    "created_in": "English",
+    "firstname": "john",
+    "lastname": "Doe"
 }
-
+```
 
 ### HTTP Method POST
 

diff --git a/docs/content/blog/.authors.yml b/docs/content/blog/.authors.yml
@@ -0,0 +1,37 @@
+authors:
+  openmage_community:
+    name: OpenMage
+    description: Community
+    avatar: https://avatars.githubusercontent.com/u/57708
+  colinmollenhour:
+    name: Colin Mollenhour
+    description: Maintainer
+    avatar: https://avatars.githubusercontent.com/u/38738
+  fballiano :
+    name: Fabrizio Balliano
+    description: Contributor
+    avatar: https://avatars.githubusercontent.com/u/909743
+  Flyingmana:
+    name: Daniel Fahlke
+    description: Contributor
+    avatar: https://avatars.githubusercontent.com/u/237319
+  kiatng:
+    name: Ng Kiat Siong
+    description: Contributor
+    avatar: https://avatars.githubusercontent.com/u/1106470
+  real34:
+    name: Pierre Martin
+    description: Contributor
+    avatar: https://avatars.githubusercontent.com/u/75968
+  r-martins:
+    name: Ricardo Martins
+    description: Contributor
+    avatar: https://avatars.githubusercontent.com/u/191149
+  robertrogge:
+    name: Robert Rogge
+    description: Contributor
+    avatar: https://avatars.githubusercontent.com/u/673488
+  sreichel:
+    name: Sven Reichel
+    description: Contributor
+    avatar: https://avatars.githubusercontent.com/u/5022236
diff --git a/docs/content/developers/guides/observer.md → .../blog/posts/guides/2022-08-17-observer.md b/docs/content/developers/guides/observer.md → .../blog/posts/guides/2022-08-17-observer.md
@@ -1,4 +1,11 @@
 ---
+title: Events & Observer
+draft: false
+date: 2022-08-17
+authors:
+  - sreichel
+categories:
+  - Guides
 tags:
   - Events
   - Debug
@@ -9,6 +16,8 @@ tags:
 
 Quick overview how observers work.
 
+<!-- more -->
+
 ## Event lookup
 
 If you want to add custom logic for `customer_login` event, add in your `config.xml`.

diff --git a/docs/content/blog/posts/guides/2023-01-09-dynamic-blocks.md b/docs/content/blog/posts/guides/2023-01-09-dynamic-blocks.md
@@ -0,0 +1,58 @@
+---
+title: Dynamic block content
+draft: false
+date: 2023-01-09
+authors:
+  - kiatng
+categories:
+  - Guides
+tags:
+  - CMS blocks
+---
+
+# Dynamic block contents in category page
+
+In _backend > Catalog > Manage Categories_, we can configure a category page and put it on the main menu. The page contents are rendered in
+
+> app\design\frontend\base\default\template\catalog\category\view.phtml
+
+If we want to render an HTML table in which its data are taken from the database, we would follow these steps:
+
+<!-- more -->
+
+## Create custom block
+
+1. Create a custom block `mymodule/mytable` with template `mymodule/mytable.phtml`.
+2. Whitelist our block for rendering in the frontend: backend > System > Permissions > Blocks
+3. Create a CMS static block: backend > CMS > Static Blocks and set the _Content_ to render from our block with this directive:
+```html
+{{block type="mymodule/mytable" template="mymodule/mytable.phtml"}}
+```
+4. Create a subcategory: backend > Catalog > Manage Categories > Add a subcategory and in the _Display Setings_ tab, set the category attribute _Display Mode_ to _Static block only_ and _CMS Block_ pointing to our block.
+
+Voila, the HTML table is rendered under the menu we just created. However, every time the table in the database is updated, and because CMS blocks rendering are taken from the cache, we would need to refresh the cache.
+
+## Render block dynamically
+
+What if the table is constantly being updated, or there is an expiry condition on some data which shouldn't be included? In which case, we would want to render the HTML table dynamically. It's actually quite easy to do:
+
+1. In the subcategory page in backend, set the _Description_ to this:
+```html
+{{block type="mymodule/mytable" template="mymodule/mytable.phtml"}}
+```
+2. Continue on to the _Display Setings_ tab and set the _CMS Block_ to _Please select a static block ..._.
+3. In our config file, either in the module `etc/config.xml` or in the `local.xml`, insert the following:
+
+```xml
+<config>
+    <global>
+        <catalog>
+            <content>
+                <tempate_filter>cms/template_filter</tempate_filter> <!-- Note the typo on template must remain as "tempate". -->
+            </content>
+        </catalog>
+    </global>
+</config>
+```
+
+That's it, the table is now rendered dynamically. There 's no need to create the CMS static block.
diff --git a/docs/content/blog/posts/guides/2023-05-01-customize-your-openmage.md b/docs/content/blog/posts/guides/2023-05-01-customize-your-openmage.md
@@ -0,0 +1,134 @@
+---
+title: Customize Your OpenMage
+draft: false
+date: 2023-08-17
+authors:
+  - colinmollenhour
+categories:
+  - Guides
+tags:
+  - Composer
+  - Patches
+  - Vendor
+---
+
+# Customize Your OpenMage
+
+When working on OpenMage or any complex PHP project, you might come across issues that require patches to be applied to third-party packages or libraries.
+These patches may be fixes or features for core code that you need to use immediately but have not yet been merged or formally released for any number of reasons.
+
+In this blog post, we'll explore the benefits of using privately maintained patches and how to use Composer and the `cweagans/composer-patches` dependency to maintain
+your own set of patches as well as how to generate patches.
+
+<!-- more -->
+
+## Benefits of Privately Maintained Patches
+
+1. Customization - Customize third-party packages or libraries to meet the specific needs of your project. This is especially useful if you need to modify functionality that is impossible to do without modifying core code or fix bugs that are not yet addressed by the package maintainers.
+2. Security - By maintaining your own patches, you can ensure that any security vulnerabilities are addressed as soon as they are discovered, without having to wait for the package maintainers to release an update.
+3. Maintainability - Privately maintained patches can help ensure your patches are organized and automatically re-applied to the core code so they don't get accidentally clobbered when updating project dependencies.
+
+## Using Composer and `cweagans/composer-patches` Dependency
+
+Composer is a dependency manager for PHP that allows you to easily manage third-party packages and libraries in your project. However, using the `cweagans/composer-patches` package
+(documentation [here](https://github.com/cweagans/composer-patches/blob/1.x/README.md)) you can also have Composer apply private patches over public dependencies. You simply define the patches in your `composer.json` file and they will be automatically applied to the
+packages or libraries that you specify when a Composer updates dependencies (`install` or `update`).
+
+Here's an example `composer.json` file with a patch defined:
+
+```json    
+{
+  "require": {
+    "vendor/package": "1.0.0"
+  },
+  "extra": {
+    "patches": {
+      "vendor/package": {
+        "Fix Bug #1234": "patches/fix-bug-1234.patch"
+      }
+    }
+  }
+}
+```
+
+In this example, we're requiring the `vendor/package` package at version `1.0.0`, and applying a patch named "Fix Bug \#1234" located in the `patches/fix-bug-1234.patch` file.
+
+To apply the patch, simply run `composer update` and Composer will apply the patch and maintain the state of whether the patch has been applied or not.
+
+## Generating patch files
+
+There are many ways to do this, but here are a few common ones:
+
+### Github Pull Requests
+
+If a Github PR already contains the code changes you need, simply download a patch file from Github by appending `.patch` to the PR url. You gotta love Github!
+
+For example, the patch URL for PR #3146 is: `https://github.com/OpenMage/magento-lts/pull/3146.patch`. This url will result in a redirect so download it with your
+browser or a client that follows redirects (Location header) such as `wget` or `curl -L`.
+
+```
+mkdir -p patches
+echo -e "Order deny,allow\nDeny from all\n" > patches/.htaccess
+curl -L https://github.com/OpenMage/magento-lts/pull/3146.patch -o var/patches/3146_Add-form-key-validation-to-Contacts-form.patch
+```
+
+Note, you can also have the patch downloaded at runtime by defining it as a url instead of a local path.
+
+```json
+{
+  "...": "...",
+  "extra": {
+    "patches": {
+      "openmage/magento-lts": {
+        "Added form key validation to Contacts form #3146": "https://github.com/OpenMage/magento-lts/pull/3146.patch"
+      }
+    }
+  }
+}
+```
+
+If it doesn't apply cleanly, apply the patch using `git apply` and fix the conflicts and then output the changes as a local patch file using one of the methods below.
+
+### symplify/vendor-patches
+
+If you are using OpenMage as a project dependency, you can use `symplify/vendor-patches` to generate a patch file easily. This tool automatically
+updates your composer.json for you. Note, in the case of modifying OpenMage core code installed as a project dependency you will need to modify the
+files in the "vendor" directory rather than the `magento-root-dir` directory (e.g. "htdocs").
+
+Here is an example generating patches for `app/Mage.php`:
+
+```sh
+composer require symplify/vendor-patches --dev
+cp vendor/app/Mage.php vendor/app/Mage.php.old
+# modify app/Mage.php to your liking
+vendor/bin/vendor-patches generate
+composer install
+```
+
+### Git with dirty working copy
+
+If you have local changes on a git working copy you can simply use `git diff > patches/my-changes.patch`.
+
+Use `git diff --cached` instead to export just the staged changes.
+
+### Git commits
+
+You can generate a patch from a branch or commit or range of commits using `git format-patch` or `git diff`. See the `--help` usage for more info but here are some examples:
+
+To get a single patch with the changes from the `some-feature` branch:
+
+```sh
+git format-patch origin/main...some-feature --stdout > patches/some-feature.patch
+```
+
+Notice the three `...` which gets all changes as one patch. If you used `..` you would get one file per commit.
+
+Use `git show <commit>` to show a single commit or `git diff <base>...<commit>` to get all changes between two commits. Consult the interwebs for more info.
+
+## Testing patches
+
+Use `git apply` or `patch` to test applying the patches to your working copy or just go for it with `composer install`.
+
+Use `composer update --lock` to save the state of the applied patches to your `composer.lock` file.
+
+Give it a try and see how privately maintained patches can benefit your project!