From c326d67f04f5544a7cf966d9513f2a896c24b28e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Mi=CC=81s=CC=8Cek?= Date: Fri, 6 Sep 2024 14:09:02 +0200 Subject: [PATCH] docs --- docs/build-php-plugin.md | 114 --------------------------------------- docs/build-php-theme.md | 90 ------------------------------- docs/index.md | 20 +++++-- docs/plugins-php.md | 90 +++++++++++++++++++++++++++++++ 4 files changed, 106 insertions(+), 208 deletions(-) delete mode 100644 docs/build-php-plugin.md delete mode 100644 docs/build-php-theme.md create mode 100644 docs/plugins-php.md diff --git a/docs/build-php-plugin.md b/docs/build-php-plugin.md deleted file mode 100644 index df24bace..00000000 --- a/docs/build-php-plugin.md +++ /dev/null @@ -1,114 +0,0 @@ -# Build a PHP plugin - -By default, plugins are compiled automatically just by copying them into the WordPress `wp-content/plugins` directory. This automatic compilation has a few disadvantages: - -- plugin is compiled every time the application gets started (time penalty). -- you need to have source code of the plugin on the server (security). -- eventual code errors are revealed upon starting the application (reliability). - -In order to avoid those issues, plugins can be pre-compiled during the deployment process. A single WordPress plugin or the `plugins` directory is then defined as a PHP class library project (below) which is then referenced by the application (see [overview](index.md)). Application can have references to one or more plugin projects. - -**Sample project**: https://github.com/iolevel/peachpie-wordpress/tree/master/MyContent - -## Plugin source files - -Sources of the plugin complies with the regular WordPress codex. See [Writing a Plugin](https://codex.wordpress.org/Writing_a_Plugin) for more details. Put the plugin source files in an empty folder. - -Following is a file structure for the basic WordPress [*Hello Dolly* plugin](https://wordpress.org/plugins/hello-dolly/). - -```shell -┬ MyHelloDollyPlugin -└┬ hello.php - └ readme.txt -``` - -Name or location of the folder are both not relevant. - -Note, the plugin must contain the standard plugin metadata. The main source file needs to specify following minimal metadata at the top of the file: - -> *hello.php:* -```php - *MyHelloDollyPlugin.msbuildproj:* -```xml - - - -``` - -For most cases, the project file does not specify anything else as all the properties are defined by default in the Sdk. In case a build property or a build item needs to be altered, add it to your project file. - -Note the project file specifies a version after the slash, i.e. `"/6.3.1-rc-016"`. This corresponds to the version of *PeachPied.WordPress.** packages which should be identical across all your application. - -## Build the plugin - -In order to build the plugin, run `dotnet build` command: - -```shell -dotnet build -``` - -The process will build the plugin project. Eventual warnings will be outputed. Any error in the code will cause the build to fail. - -> If the process is run for the first time, it will first download the project Sdk and dependency packages (it means it requires an Internet connection). - -### Add plugin to the application - -Assuming you have ASP.NET Core Application (called *app*) with WordPress (see [quick start](index.md#quick-start)). Adding plugins to the application is equivalent to adding project references or package references. - -Either add project reference to the plugin in Visual Studio IDE, or on command line, or edit the application's project file: - -> *app.csproj:* -```xml - - - -``` - -> Note, the plugin is referenced by the application and it still needs to be activated in WordPress dashboard. - -## Package the plugin - -Plugin can be packed into a standard NuGet package. Run `dotnet pack` command to create NuGet package: - -```shell -dotnet pack -``` - -Package (*.nupkg*) can be pushed into a NuGet feed. It is recommended to push packages to private feeds, or at least pack packages with a unique prefixed package identifier (i.e. *MyName.MyWpPlugins.MyHelloDollyPlugin*). - -### Add package reference to the application - -Once plugin is packed and available on a NuGet feed, it can be referenced as a package reference. Either add package reference to the plugin in Visual Studio IDE, or on command line, or edit the application's project file: - -```xml - - - -``` - -## Debugging the plugin - -> not yet documented \ No newline at end of file diff --git a/docs/build-php-theme.md b/docs/build-php-theme.md deleted file mode 100644 index 4a0fd9ec..00000000 --- a/docs/build-php-theme.md +++ /dev/null @@ -1,90 +0,0 @@ -# Build a PHP theme - -Please see [Build a Plugin](build-php-plugin.md) for more details. - -Single theme for WordPress or the whole `themes` directory is defined as a PHP class library project (below) which is then referenced by the application. Application can have references to one or more themes. - -**Sample project**: https://github.com/iolevel/peachpie-wordpress/tree/master/MyContent - -## Theme source files - -Sources of the theme complies with the regular WordPress codex. See [Theme Handbook](https://developer.wordpress.org/themes/) for more details. - -Put the theme source files in an empty folder. Name or location of the folder are both not relevant. - -## Theme project file - -In order to compile the theme, create a project file in the theme folder. - -```shell -┬ MyWordPressTheme -└┬ MyWordPressTheme.msbuildproj <--- - ├ readme.txt - └ ... -``` - -By default, the name of the project file represents the theme's *id*. *Id*, or *slug id* is the identifier of the theme within WordPress. Also it denotates the folder name in which the theme files will be placed within `wp-content` directory. - -Project file is an XML file with the following content: - -> *MyWordPressTheme.msbuildproj:* -```xml - - - themes - - -``` - -Note the project file specifies a version after the slash, i.e. `"/6.3.1-rc-016"`. This corresponds to the version of *PeachPied.WordPress.** packages which should be identical across all your application. - -## Build the theme - -In order to build the theme, run `dotnet build` command: - -```shell -dotnet build -``` - -The process will build the theme project. Eventual warnings will be outputed. Any error in the code will cause the build to fail. - -> If the process is run for the first time, it will first download the project Sdk and dependency packages (it means it requires an Internet connection). - -### Add theme to the application - -Assuming you have ASP.NET Core Application (called *app*) with WordPress (see [quick start](index.md#quick-start)). Adding themes to the application is equivalent to adding project references or package references. - -Either add project reference to the theme in Visual Studio IDE, or on command line, or edit the application's project file: - -> *app.csproj:* -```xml - - - -``` - -> Note, the theme is referenced by the application and it still needs to be activated in WordPress dashboard. - -## Package the theme - -Theme can be packed into a standard NuGet package. Run `dotnet pack` command to create NuGet package: - -```shell -dotnet pack -``` - -Package (*.nupkg*) can be pushed into a NuGet feed. It is recommended to push packages to private feeds, or at least pack packages with a unique prefixed package identifier (i.e. *MyName.MyWpThemes.MyWordPressTheme*). - -### Add package reference to the application - -Once the theme is packed and available on a NuGet feed, it can be referenced as a package reference. Either add package reference to the theme in Visual Studio IDE, or on command line, or edit the application's project file: - -```xml - - - -``` - -## Debugging the theme - -> not yet documented \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 91fc1461..2855e21c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -65,7 +65,15 @@ Besides regular WordPress dashboard pages, WpDotNet adds an informational panel The panel provides information about the current .NET runtime version, consumed memory, or total CPU time spent in the whole application. Note that the values are reset if the process is restarted. -## Remarks +## Differences + +The main differences between regular WordPress running on PHP and WpDotNet running on .NET are: + +- The .NET application and all its [plugins/themes](plugins-php.md) need to be compiled before running. Plugins and themes cannot be added after building the project. +- The WordPress configuration is not set in `wp-config.php` file anymore. WpDotNet uses ASP.NET Core configuration providers like `appsettings.json`. See [configuration](configuration.md). +- There is literally no `php` intepreter; all the PHP standard functions and extensions are re-implemented in .NET and their behavior may differ, i.e. break some functionality. In such case please let us know. + +## Notes - Permalinks are implicitly enabled through the URL rewriting feature. - WordPress debugging is implicitly enabled when running in a *Development* environment (debugging in your IDE). @@ -73,8 +81,12 @@ The panel provides information about the current .NET runtime version, consumed - Response caching and response compression are enabled by default when user is not logged in. - Most of the original `.php` files are not present on the file system and cannot be edited. -## Related links +## Next Steps + +- [Tutorial: Build ASP.NET Core app with WordPress](tutorials/aspnetcore-wordpress.md): Step-by-step creating WordPress app in Visual Studio. +- [Add WordPress Plugins/Themes](plugins-php.md): Extend WpDotNet with WordPress/PHP plugins and themes from `.php` sources. +- [Public NuGet Release](https://www.nuget.org/packages/PeachPied.WordPress.AspNetCore/): Free WpDotNet release versions. + +--- -- https://www.wpdotnet.com/ -- https://www.nuget.org/packages/PeachPied.WordPress.AspNetCore/ [![NuGet](https://img.shields.io/nuget/v/PeachPied.WordPress.AspNetCore.svg)](https://www.nuget.org/packages/PeachPied.WordPress.AspNetCore/) diff --git a/docs/plugins-php.md b/docs/plugins-php.md new file mode 100644 index 00000000..e8fc593e --- /dev/null +++ b/docs/plugins-php.md @@ -0,0 +1,90 @@ +# Plugins and Themes (.php) + +Plugins and themes (either your own or plugins and themes downloaded from [WordPress directory](https://wordpress.org/plugins/)) need to be added during the development process and compiled. This article describes how and how it works. + +**Sample project**: https://github.com/iolevel/peachpie-wordpress/tree/master/MyContent + +## Project Structure + +The following project structure respects the `/wp-content/` directory used by WordPress. Sources of the plugin complies with the regular WordPress codex. See [Writing a Plugin](https://codex.wordpress.org/Writing_a_Plugin) for more details. Put the plugin source files in `plugins` folder, and themes in `themes` folder (as you would do in WordPress). + +Following is the file structure for the basic WordPress [*Hello Dolly* plugin](https://wordpress.org/plugins/hello-dolly/). + +```shell +┬ MyContent +└ plugins + └ hello.php +``` + +Name of the folder is not relevant. + +Note, the plugin must contain the standard plugin metadata. The main source file needs to specify following minimal metadata at the top of the file: + +> *hello.php:* +```php + *MyContent.msbuildproj:* +```xml + + +``` + +For most cases, the project file does not specify anything else as all the properties are defined by default in the Sdk. In case a build property or a build item needs to be altered, add it to your project file. + +Note the project file specifies a version after the slash, i.e. `"/6.5.4-rc-020"`. This corresponds to the version of *PeachPied.WordPress.** packages which should be identical across all your application. + +## Build + +In order to build plugins and themes, run `dotnet build` command: + +```shell +dotnet build +``` + +The process will build the project. Eventual warnings will be outputed. Any error in the code will cause the build to fail. + +> If the process is run for the first time, it will first download the project Sdk and dependency packages (it means it requires an Internet connection). + +### Build Errors + +Building the project may result in compile-time errors. It is very common for a WordPress plugin to contain an invalid code. + +Errors need to be fixed. Sometimes whole files or directories may be excluded from the compilation since they may contain a dead code (usually tests or adapters for other plugins you don't use). + +### Add Project Reference + +Assuming you have ASP.NET Core Application (named *app*) with WordPress (see [quick start](index.md#quick-start)), add project reference to `MyContent.msbuildproj`. + +Either add project reference to the plugin in Visual Studio IDE, or on command line, or edit the application's project file: + +> *app.csproj:* +```xml + + + +``` + +> Note, the plugin still needs to be activated in WordPress dashboard once you compile and run the application. + +## Debugging the plugin +