-
Notifications
You must be signed in to change notification settings - Fork 62
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Create 2023-05-01-customize-your-openmage.md #122
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,126 @@ | ||
--- | ||
layout: post | ||
title: Customize Your OpenMage | ||
category: Guest post | ||
thumbnail: https://user-images.githubusercontent.com/38738/235500971-0a80cf68-8708-4166-8e50-3084bd0342d0.jpg | ||
author: Colin Mollenhour | ||
permalink: /:year/:month/:day/:title:output_ext | ||
lang: en | ||
show_in_blog_page_last_posts_section: yes | ||
--- | ||
|
||
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. | ||
|
||
# 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! |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Line can be removed. Was added as dev-req with zf1f.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm, it was necessary when I tried it.. I think to use it in a project which has openmage as a dependency I think it is still required because dev dependencies of packages are not installed by default. The guide is written for users which would be using openmage as a dependency, not the openmage devs.