{"id":24271466,"url":"https://github.com/r0wi-dev/workflow_ocr","last_synced_at":"2026-01-24T22:13:01.617Z","repository":{"id":37041355,"uuid":"255956367","full_name":"R0Wi-DEV/workflow_ocr","owner":"R0Wi-DEV","description":"This is a Nextcloud Workflow App which enables you to process files via OCR on serverside.","archived":false,"fork":false,"pushed_at":"2025-04-09T19:41:11.000Z","size":4194,"stargazers_count":83,"open_issues_count":7,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-09T20:22:44.811Z","etag":null,"topics":["nextcloud","nextcloud-workflow-ocr","ocr","pdf-files"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/R0Wi-DEV.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-15T15:18:10.000Z","updated_at":"2025-04-09T19:16:13.000Z","dependencies_parsed_at":"2023-02-15T22:45:50.246Z","dependency_job_id":"c1115f4b-ee87-4c6c-9726-fc30a980ad03","html_url":"https://github.com/R0Wi-DEV/workflow_ocr","commit_stats":null,"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R0Wi-DEV%2Fworkflow_ocr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R0Wi-DEV%2Fworkflow_ocr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R0Wi-DEV%2Fworkflow_ocr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/R0Wi-DEV%2Fworkflow_ocr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/R0Wi-DEV","download_url":"https://codeload.github.com/R0Wi-DEV/workflow_ocr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248146756,"owners_count":21055391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nextcloud","nextcloud-workflow-ocr","ocr","pdf-files"],"created_at":"2025-01-15T17:24:49.147Z","updated_at":"2026-01-24T22:13:01.610Z","avatar_url":"https://github.com/R0Wi-DEV.png","language":"PHP","funding_links":["https://www.buymeacoffee.com/R0Wi"],"categories":[],"sub_categories":[],"readme":"\n# Nextcloud Workflow OCR app\n![PHPUnit](https://github.com/R0Wi/workflow_ocr/workflows/PHPUnit/badge.svg)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=R0Wi_workflow_ocr\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=R0Wi_workflow_ocr)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=R0Wi_workflow_ocr\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=R0Wi_workflow_ocr)\n![Lint](https://github.com/R0Wi/workflow_ocr/workflows/Lint/badge.svg)\n[![Generic badge](https://img.shields.io/github/v/release/R0Wi/workflow_ocr)](https://github.com/R0Wi/workflow_ocr/releases)\n[![Generic badge](https://img.shields.io/badge/Nextcloud-34-orange)](https://github.com/nextcloud/server)\n\n[![\"Buy Me A Coffee\"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/R0Wi)\n\n## Table of contents\n\n- [Nextcloud Workflow OCR app](#nextcloud-workflow-ocr-app)\n  - [Table of contents](#table-of-contents)\n  - [Setup](#setup)\n    - [App installation](#app-installation)\n    - [Nextcloud background jobs](#nextcloud-background-jobs)\n    - [Backend](#backend)\n      - [Local installation](#local-installation)\n      - [`workflow_ocr_backend` installation](#workflow_ocr_backend-installation)\n    - [Setup Checks](#setup-checks)\n  - [Usage](#usage)\n    - [Useful triggers](#useful-triggers)\n      - [Trigger OCR if file was created or updated](#trigger-ocr-if-file-was-created-or-updated)\n      - [Trigger OCR on tag assigning](#trigger-ocr-on-tag-assigning)\n    - [Settings](#settings)\n      - [Per workflow settings](#per-workflow-settings)\n      - [Global settings](#global-settings)\n    - [Testing your configuration](#testing-your-configuration)\n    - [Get feedback via Notifications](#get-feedback-via-notifications)\n  - [How it works](#how-it-works)\n    - [General](#general)\n    - [PDF](#pdf)\n    - [Images](#images)\n  - [Troubleshooting](#troubleshooting)\n    - [Generic troubleshooting guide](#generic-troubleshooting-guide)\n    - [The Nextcloud Workflowengine](#the-nextcloud-workflowengine)\n  - [Development](#development)\n    - [Dev setup](#dev-setup)\n    - [Debugging](#debugging)\n    - [`docker`-based setup](#docker-based-setup)\n    - [Executing tests](#executing-tests)\n    - [Adding a new `OcrProcessor`](#adding-a-new-ocrprocessor)\n    - [Events emitted by the app](#events-emitted-by-the-app)\n      - [`TextRecognizedEvent`](#textrecognizedevent)\n  - [Limitations](#limitations)\n  - [Used libraries \\\u0026 components](#used-libraries--components)\n\n## Setup\n### App installation\nFirst download and install the Nextcloud Workflow OCR app from the official [Nexcloud-appstore](https://apps.nextcloud.com/apps/workflow_ocr) or by downloading the appropriate tarball from the [releases](https://github.com/R0Wi/workflow_ocr/releases) page. \n```bash\ncd /var/www/\u003cNEXTCLOUD_INSTALL\u003e/apps\nwget https://github.com/R0Wi/workflow_ocr/releases/download/\u003cVERSION\u003e/workflow_ocr.tar.gz\ntar -xzvf workflow_ocr.tar.gz\nrm workflow_ocr.tar.gz\n```\n### Nextcloud background jobs\nSince the actual processing of the files is done asynchronously via Nextcloud's background job engine, make sure you've properly setup the cron functionallity as described [here](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/background_jobs_configuration.html#cron-jobs). If possible please use the [`crontab`](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/background_jobs_configuration.html#cron) approach for more reliability.\n\n\n### Backend\n\nThis app is based on `ocrmypdf`. You can either install the CLI directly on the server running Nextcloud or use the alternative backend setup via Docker.\n\n#### Local installation\n\n\u003e :warning: Since `v1.20.1` you'll have to install `OCRmyPDF`.\n\nIn the backend [`OCRmyPDF`](https://github.com/jbarlow83/OCRmyPDF) is used for processing PDF files. Make sure you have this commandline tool installed. Make sure you have the appropriate version (see below, Used libraries').\n\n```bash\napt-get install ocrmypdf\n``` \n\nThe `ocrmypdf` CLI can also convert single image files (`jpg`/`png`) to PDF before processing it via OCR. This mode is also supported by this app. You can read more about it in the [official docs](https://ocrmypdf.readthedocs.io/en/latest/cookbook.html#option-use-ocrmypdf-single-images-only).\n\nAlso if you want to use specific **language settings** please [install the corresponding `tesseract` packages](https://ocrmypdf.readthedocs.io/en/latest/languages.html).\n\n```bash\n# English\napt-get install tesseract-ocr-eng\n\n# German\napt-get install tesseract-ocr-deu\n\n# Chinese - Simplified\napt-get install tesseract-ocr-chi-sim\n```\n\n#### `workflow_ocr_backend` installation\n\nStarting from version 30, Nextcloud added support for [AppApi](https://docs.nextcloud.com/server/latest/admin_manual/exapps_management/AppAPIAndExternalApps.html) apps. In essence this allows external container based applications to be integrated into the Nextcloud ecosystem. This app is using this feature to provide an alternative backend setup via Docker.\n\nIf everything is setup properly, you can just install the `workflow_ocr_backend` app from the [appstore](https://apps.nextcloud.com/apps/workflow_ocr_backend).\n\nPlease refer to **https://github.com/R0Wi-DEV/workflow_ocr_backend** for more information on how to setup the backend.\n\n\u003e :information_source: If the `workflow_ocr_backend` External App is installed, this \"frontend\" app will automatically use it as the backend even if you installed `ocrmypdf` locally.\n\n### Setup Checks\n\nThe app will perform some [Setup Checks](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/security_setup_warnings.html) to verify your installation. If there is any problem with your backend setup, you'll see an error printed in Nextcloud under `Administration Settings` \u0026#8594; `Overview` \u0026#8594; `Security \u0026 setup warnings`.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"50%\" src=\"doc/img/setup_checks.jpg\" alt=\"Setup checks\"\u003e\n\u003c/p\u003e\n\n## Usage\nYou can configure the OCR processing via Nextcloud's workflow engine. Therefore configure a new flow via `Settings` \u0026#8594; `Flow` \u0026#8594; `Add new flow` (if you don't see `OCR file` here the app isn't installed properly or you forgot to activate it).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"50%\" src=\"doc/img/usage_1.jpg\" alt=\"Usage setup\"\u003e\n\u003c/p\u003e\n\n### Useful triggers\n\n#### Trigger OCR if file was created or updated\n\nIf you want a newly uploaded file to be processed via OCR or if you want to process a file which was updated, use the **When**-conditions `File created` or `File updated` or both.\n\nA typical setup for processing incoming PDF-files and adding a text-layer to them might look like this:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"75%\" src=\"doc/img/usual_config_1.jpg\" alt=\"PDF setup\"\u003e\n\u003c/p\u003e\n\n\u003e :warning: Please ensure to use the `File MIME type` \u0026#8594; **`is`** \u0026#8594; `PDF documents` operator, otherwise you might not be able to save the workflow like discussed [here](https://github.com/R0Wi/workflow_ocr/issues/41).\n\n#### Trigger OCR on tag assigning\n\nIf you have existing files which you want to process after they have been created, or if you want to filter manually which files are processed, you can use the `Tag assigned` event to trigger the OCR process if a user adds a specific tag to a file. Such a setup might look like this:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"75%\" src=\"doc/img/tag_assigned_config.png\" alt=\"Tag assigned setup\"\u003e\n\u003c/p\u003e\n\nAfter that you should be able to add a file to the OCR processing queue by assigning the configured tag to a file:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"75%\" src=\"doc/img/assign_tag_1.png\" alt=\"Tag assign frontend 1\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"50%\" src=\"doc/img/assign_tag_2.png\" alt=\"Tag assign frontend 2\"\u003e\n\u003c/p\u003e\n\n### Settings\n\n#### Per workflow settings\nAnyone who can create new workflows (admin or regular user) can configure settings for the OCR processing for a specific workflow. These settings are only applied to the specific workflow and do not affect other workflows.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"75%\" src=\"doc/img/per_workflow_settings.jpg\" alt=\"Per workflow settings\"\u003e\n\u003c/p\u003e\n\nCurrently the following settings are available per workflow:\n\nName | Description\n--- | ---\nOCR language | The languages to be used for OCR processing. The languages can be choosen from a dropdown list. For PDF files this setting corresponds to the `-l` parameter of `ocrmypdf`. **Please note** that you'll have to install the appropriate languages like described in the [`ocrmypdf` documentation](https://ocrmypdf.readthedocs.io/en/latest/languages.html).\nAssign tags after OCR | These tags will be assigned to the file after it has been successfully processed. |\nRemove tags after OCR | These tags will be removed from the file after it has been successfully processed. If the file does not have the tag, it will just be skipped. |\nOCR mode | Controls the way files are processed, which already have OCR content. For PDF files this setting corresponds to the `--skip-text`, `--redo-ocr` and `--force-ocr` parameters of `ocrmypdf`. See [official docs](https://ocrmypdf.readthedocs.io/en/latest/advanced.html#when-ocr-is-skipped) for additional information.\u003cbr\u003e**Skip text:** skip pages completely that already contain text. Such a page will not be touched and just be copied to the final output.\u003cbr\u003e**Redo OCR:** perform a detailed text analysis to split up pages into areas with and without text.\u003cbr\u003e**Force OCR:** all pages will be rasterized to images and OCR will be performed on every page. |\nKeep original file version | If the switch is set, the original file (before applying OCR) will be kept. This is done by giving the file version the label `Before OC`. This version will be excluded from the automatic expiration process (see [here](https://docs.nextcloud.com/server/latest/user_manual/en/files/version_control.html#naming-a-version) for details) |\nKeep original file modification date | Restore the modification date of the original file. The original modification date will be applied to the newly created file version. This is useful if you need to preserve the file modification date, for example to be able to sort files accordingly. |\nSend success notification | Usually the workflow would only send a notification to the user if the OCR process failed. If this option is activated, the user will also be notified if a document has been processed successfully via OCR. |\nSkip notifications for invalid PDFs | When set, notifications for `ocrmypdf` exit code 2 failures (for example digitally signed or otherwise invalid PDFs) are suppressed so the workflow stays quiet unless another error occurs. |\nSkip notifications for encrypted PDFs | When set, notifications for `ocrmypdf` exit code 8 failures (for example password-protected PDFs) are suppressed so only other failure cases trigger alerts. |\nRemove background\\* | If the switch is set, the OCR processor will try to remove the background of the document before processing and instead set a white background. For PDF files this setting corresponds to the [`--remove-background`](https://ocrmypdf.readthedocs.io/en/latest/cookbook.html?highlight=remove-background#image-processing) parameter of `ocrmypdf`.\u003cbr/\u003e:warning: Please note that this flag will currently only work with **`ocrmypdf` versions prior to 13**. It might be added in future versions again. See [here](https://github.com/ocrmypdf/OCRmyPDF/issues/884) for details. :warning:|\nCustom ocrMyPdf CLI arguments | If you want to pass custom arguments to the `ocrmypdf` CLI, you can do so here. Please note that the arguments will be passed as they are to the CLI, so make sure to use the correct syntax. Check the [official docs](https://ocrmypdf.readthedocs.io/en/latest/cookbook.html) for more information. |\nCreate sidecar text file | If this option is set, the workflow will create a text file next to the OCR processed file containing the extracted text. The file will be named like the OCR processed file but with a `.txt` file extension. For example, if your file was named `my-file.pdf`, the sidecar file will be named `my-file.txt` and will be created within the same folder. For an image file `photo.jpg` that gets converted to `photo.jpg.pdf`, the sidecar file will be `photo.jpg.txt`. |\n\n\n\n\\* *For `ocrmypdf` the parameter `--remove-background` is [incompatible with `--redo-ocr`](https://github.com/ocrmypdf/OCRmyPDF/blob/110c75cba25121dcca7e2b91644206cce29e8430/src/ocrmypdf/_validation.py#L104).*\n\n#### Global settings\nAs a Nextcloud administrator you're able to configure global settings which apply to all configured OCR-workflows on the current system.\nGo to `Settings` \u0026#8594; `Flow` and scroll down to `Workflow OCR`:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"75%\" src=\"doc/img/global_settings.png\" alt=\"Global settings\"\u003e\n\u003c/p\u003e\n\nCurrently the following settings can be applied globally:\n\nName | Description\n-----|------------\nProcessor cores | Defines the number of processor cores to use for OCR processing. When the input is a PDF file, this corresponds to the [`ocrmypdf` CPU limit](https://ocrmypdf.readthedocs.io/en/latest/pdfsecurity.html?highlight=%22-j%22#limiting-cpu-usage). This setting can be especially useful if you have a small backend system which has only limited power.\nRequest timeout | Defines a global timeout (in seconds) when using the `workflow_ocr_backend` app. Use this to limit how long the app will wait for OCR responses. Default value is 60 seconds. |\n\n### Testing your configuration\n\nTo **test** if your file gets processed properly you can do the following steps:\n1. Upload a new file which meets the criteria you've recently defined in the workflow creation.\n2. Go to your servers console and change into the Nextcloud installation directory (e.g. `cd /var/www/html/nextcloud`).\n3. Execute the cronjob file manually e.g. by typing `sudo -u www-data php cron.php ` (this is the command you usually setup to be executed by linux crontab).\n4. If everything went fine you should see that there was a new version of your file created. If you uploaded a PDF file you should now be able to select text in it if it contained at least one image with scanned text.\n  \u003cp align=\"center\"\u003e\n    \u003cimg width=\"75%\" src=\"doc/img/file_versions.jpg\" alt=\"File versions\"\u003e\n  \u003c/p\u003e\n\n### Get feedback via Notifications\n\nThe Workflow OCR app supports sending notifications to the user in case anything went wrong during the [asynchronous OCR processing](#how-it-works). To enable this feature, you have to install and enable the [`Notifications`](https://github.com/nextcloud/notifications) app in your Nextcloud instance.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"30%\" src=\"doc/img/notifications.png\" alt=\"Notifications\"\u003e\n\u003c/p\u003e\n\n\n## How it works\n### General\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"50%\" src=\"doc/diagramms/general.png\" alt=\"General diagramm\"\u003e\n\u003c/p\u003e\n\n### PDF\nFor processing PDF files, the external command line tool [`OCRmyPDF`](https://github.com/jbarlow83/OCRmyPDF) is used. The tool is always invoked with the [`--skip-text`](https://ocrmypdf.readthedocs.io/en/latest/advanced.html#when-ocr-is-skipped) parameter so that it will skip pages which already contain text. Please note that with that parameter set, it's currently not possible to analize pages with mixed content (see https://github.com/R0Wi/workflow_ocr/issues/113 for furhter information).\n\n### Images\nFor processing single images (currently `jpg` and `png` are supported), `ocrmypdf` converts the image to a PDF. The converted PDF file will then be OCR processed and saved as a new file with the original filename and the extension `.pdf` (for example `myImage.jpg` will be saved to `myImage.jpg.pdf`). The original image fill will remain untouched.\n\nNote about PNG alpha channel: The OCR processing will remove (flatten) the alpha/transparency channel from PNG images before conversion. Transparent areas are filled with a white background to make the OCR process possible with `ocmypdf`. This behavior applies automatically to PNG images processed by the app. See [this issue](https://github.com/R0Wi-DEV/workflow_ocr/issues/295) for details.\n\n## Troubleshooting\n\n### Generic troubleshooting guide\n\nSince this app does its main work asynchronously, controlled by the NC cron, the troubleshooting gets slightly more complicated. That's why we suggest to follow this guide if you're facing any issues:\n\n1. Create your OCR workflow with triggers and conditions to your taste\n2. Temporarily decrease the servers [loglevel](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/logging_configuration.html#log-level) to `0`\n3. Try to trigger the workflow according to the conditions you've set (for example by uploading a new PDF file or setting a new tag)\n4. Check your Database table `oc_jobs`. This should contain a new job for the OCR processing like this: `| OCA\\WorkflowOcr\\BackgroundJobs\\ProcessFileJob | {\"filePath\":\"some.pdf\",\"settings\":\"{\\\"languages\\\":[\\\"eng\\\"]}\"}`. If that's not the case, you can stop here. You're facing a condition issue. The `nextcloud.log` file content might help you to find out why your workflow was not added to the queue\n5. If you can see a new job for the OCR process, run the [cron.php](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/background_jobs_configuration.html#cron) once manually (for example by running `sudo -u www-data php -f /var/www/nextcloud/cron.php`)\n6. Inspect your `nextcloud.log` file (e.g. by using the [logreader](https://github.com/nextcloud/logreader)). You should be able to see various outputs, pointing you to the right direction (for example you should be able to see the output of the `ocrmypdf` process)\n\n### The Nextcloud Workflowengine\n\nThis app is build on top of the [Nextcloud Workflowengine](https://nextcloud.com/de/workflow/) which makes it quite flexible and customizable. But this comes with the tradeoff that some missbehaviours might be related to the app itself and some others have their origin in the Workflowengine. As a rule of thumb, everything related to the lefhandside triggers and conditions secions comes from the NC Workflowengine, while the settings on the righthandside are OCR app specific:\n\n  \u003cp align=\"center\"\u003e\n    \u003cimg src=\"doc/img/workflowengine_delimitation.jpg\" width=\"75%\" alt=\"NC Workflowengine\"\u003e\n  \u003c/p\u003e\n\nPlease keep that in mind when troubleshooting issues. Of course, feel free to open new issues here, but we might need to redirect you to the [official NC Server project](https://github.com/nextcloud/server).\n\nYou can check issues related to the Workflowengine by trying to reproduce the same behaviour with different [workflow-based apps](https://apps.nextcloud.com/categories/workflow). If they behave in the same way in terms of triggers and conditions, the issue is most likely related to the NC Workflowengine itself and cannot be fixed here.\n## Development\n\n### Dev setup\nTools and packages you need for development:\n* `make`\n* `node` and `npm`\n* [`composer`](https://getcomposer.org/download/) (Will be automatically installed when running `make build`)\n* Properly setup `php`-environment\n* Webserver (like [`Apache`](https://httpd.apache.org/))\n* [`XDebug`](https://xdebug.org/docs/install) and a `XDebug`-connector for your IDE (for example https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug) if you want to debug PHP code\n* PHP IDE (we recommend [`VSCode`](https://code.visualstudio.com/))\n\nYou can then build and install the app by cloning this repository into the Nextcloud apps folder and running `make build`.\n```bash\ncd /var/www/\u003cNEXTCLOUD_INSTALL\u003e/apps\ngit clone https://github.com/R0Wi/workflow_ocr.git workflow_ocr\ncd workflow_ocr\nmake build\n```\nDon't forget to activate the app via Nextcloud web-gui.\n\n### Debugging\nWe provide a preconfigured debug configuration file for `VSCode` at `.vscode/launch.json` which will automatically be recognized when opening this \nrepository inside of `VSCode`. If you've properly installed and configured the `XDebug`-plugin you should be able to see it in the upper left corner\nwhen being inside of the debug-tab.\n\n  \u003cp align=\"center\"\u003e\n    \u003cimg src=\"doc/img/debug.jpg\" alt=\"VSCode debug profile\"\u003e\n  \u003c/p\u003e\n\nTo get the debugger profiles working you need to ensure that `XDebug` for `Apache` (or your preferred webserver) and `XDebug` for PHP CLI both connect to your machine at\nport `9003`. Depending on your system a possible configuration could\nlook like this:\n\n```ini\n; /etc/php/8.4/cli/php.ini\n; ...\n[Xdebug]\nzend_extension=/usr/lib/php/20190902/xdebug.so\nxdebug.remote_enable=1\nxdebug.remote_host=127.0.0.1\nxdebug.remote_port=9003\nxdebug.remote_autostart=1\n```\n\n```ini\n; /etc/php/8.4/apache2/php.ini\n; ...\n[Xdebug]\nzend_extension=/usr/lib/php/20190902/xdebug.so\nxdebug.remote_enable=1\nxdebug.remote_host=127.0.0.1\nxdebug.remote_port=9003\nxdebug.remote_autostart=1\n```\n\nThe following table lists the various debug profiles:\n\n| Profile name            | Use                                                                                           |\n|-------------------------|-----------------------------------------------------------------------------------------------|\n| Listen for XDebug       | Starts XDebug listener for your webserver process.                                            |\n| Listen for XDebug (CLI) | Starts XDebug listener for your php cli process.                                              |\n| Run cron.php            | Runs Nextcloud's `cron.php` with debugger attached. Useful for debugging OCR-processing jobs. |\n| Debug Unittests         | Start PHPUnit Unittests with debugger attached.                                               |\n| Debug Integrationtests  | Start PHPUnit Integrationtests with debugger attached.                                        |\n\nIf you're looking for some good sources on how to setup `VSCode` + `XDebug` we can recommend:\n* https://tighten.co/blog/configure-vscode-to-debug-phpunit-tests-with-xdebug/\n* https://code.visualstudio.com/docs/languages/php\n\n### `docker`-based setup\nIf you're interested in a `docker`-based setup we can recommend\nthe images from https://github.com/thecodingmachine/docker-images-php which already come with `Apache` and\n`XDebug` installed.\n\nA working `docker-compose.yml`-file could look like this:\n```yaml\nversion: '3'\nservices:\n  apache_dev:\n    restart: always\n    container_name: apache_dev\n    image: ${IMAGE}-custom\n    build:\n      dockerfile: ./Dockerfile\n      args:\n        IMAGE: ${IMAGE}\n    environment:\n      - PHP_INI_MEMORY_LIMIT=1g\n      - PHP_INI_ERROR_REPORTING=E_ALL\n      - PHP_INI_XDEBUG__START_WITH_REQUEST=yes\n      - PHP_INI_XDEBUG__LOG_LEVEL=7\n      - PHP_EXTENSIONS=xdebug gd intl bcmath gmp imagick\n    volumes:\n      - ./html:/var/www/html\n      - ./000-default.conf:/etc/apache2/sites-enabled/000-default.conf\n    ports:\n      - 80:80\n    networks:\n      - web_dev\n```\n`IMAGE` could be set to `IMAGE=thecodingmachine/php:8.4-v4-apache-node14` and the content of `Dockerfile` might\nlook like this:\n\n```dockerfile\nARG IMAGE\nFROM $IMAGE\n\nUSER root\nRUN    apt-get update \\\n    \u0026\u0026 apt-get install -y make ocrmypdf tesseract-ocr-eng tesseract-ocr-deu smbclient \\\n    \u0026\u0026 apt-get clean \\\n    \u0026\u0026 rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*\nUSER docker\n```\n\u003e :information_source: Please note that these are just\nworking snippets which you might have to modify to fit\nyour needs.\n\n### Executing tests\nTo execute the implemented PHPUnit tests you can use one of the following commands:\n\n```bash\n# Only run unittests\nmake unittest\n\n# Only run integrationtests\nmake integrationtest\n\n# Run all tests\nmake test\n\n# Run all tests and create HTML coverage report\nmake html-coverage\n\n# Run all tests and create XML coverage report\nmake coverage\n```\n\u003e :warning: Make sure you activated the app before you run any tests (`php occ app:enable workflow_ocr`). Otherwise the initialization will fail.\n\n### Adding a new `OcrProcessor`\nTo support a new mimetype for being processed with OCR you have to follow a few easy steps:\n1. Create a new class in `lib/OcrProcessors` and let the class implement the interface `IOcrProcessor`.\n2. Register your implementation in `lib/OcrProcessors/OcrProcessorFactory.php` by adding it to the mapping.\n```php\nprivate static $mapping = [\n        'application/pdf' =\u003e PdfOcrProcessor::class,\n\t\t// Add your class here, for example:\n\t\t'mymimetype' =\u003e MyOcrProcessor::class\n    ];\n```\n3. Register a factory for creating your newly added processor in `lib/OcrProcessors/OcrProcessorFactory.php` by adding an appropriate function inside of `registerOcrProcessors`.\n```php\npublic static function registerOcrProcessors(IRegistrationContext $context) : void {\n\t\t// [...]\n\t\t$context-\u003eregisterService(MyOcrProcessor::class, function(ContainerInterface $c) {\n\t\t\treturn new /* your factory goes here */\n\t\t}, false);\n\t}\n```\n\nThat's all. If you now create a new workflow based on your added mimetype, your implementation should be triggered by the app. The return value of `ocrFile(string $fileContent, WorkflowSettings $settings, GlobalSettings $globalSettings)` will be interpreted as the file content of the scanned file. This one is used to create a new file version in Nextcloud.\n\n### Events emitted by the app\n\nThe app currently emits the following events from `lib/Events`. You can use these hooks to extend the app's functionality inside your own app.\nUse the following sample code to implement  a listener for the events:\n\n```php\nuse OCA\\WorkflowOcr\\Events\\TextRecognizedEvent;\nuse OCP\\EventDispatcher\\Event;\nuse OCP\\EventDispatcher\\IEventListener;\n\nclass TextRecognizedListener implements IEventListener {\n\tpublic function handle(Event $event): void {\n\t\tif (!$event instanceof TextRecognizedEvent) {\n\t\t\treturn;\n\t\t}\n\t\t// Do something with the event ...\n\t}\n}\n```\n\nYour implementation should then be registered in your app's `Application.php`:\n\n```php\npublic function register(IRegistrationContext $context): void {\n\t\t$context-\u003eregisterEventListener(TextRecognizedEvent::class, TextRecognizedListener::class);\n}\n```\n\n#### `TextRecognizedEvent`\n\nThis event will be emitted when a OCR process has finished successfully. It contains the following information:\n\n| Method | Type | Description |\n|--------|-------|------------|\n| `getRecognizedText()` | `string` | Contains the text which was recognized by the OCR process. |\n| `getFile()`   | `OCP\\Files\\File` | The NC file node where the OCR processed file was stored to. |\n\n\u003e **Note:** this event will be emitted even if the OCR content was empty.\n\n## Limitations\n* **Currently only pdf documents (`application/pdf`) and single images (`image/jpeg` and `image/png`) can be used as input.** Other mimetypes are currently ignored but might be added in the future.\n* All input file types currently produce a single `pdf` output file. Currently there is no other output file format supported.\n* Pdf metadata (like author, comments, ...) might not be available in the converted output pdf document. This is limited by the capabilities of `ocrmypdf` (see https://github.com/ocrmypdf/OCRmyPDF/issues/327).\n* Currently files are only processed based on workflow-events so there is no batch-mechanism for applying OCR to already existing files. This is a feature which might be added in the future. For applying OCR to a single file, which already exist, one could use the [\"tag assigned\"](#trigger-ocr-on-tag-assigning) workflow trigger.\n* If you encounter any problems with the OCR processing, you can always restore the original file via Nextcloud's version history.\n  \u003cp align=\"center\"\u003e\n    \u003cimg width=\"75%\" src=\"doc/img/file_versions.jpg\" alt=\"File versions\"\u003e\n  \u003c/p\u003e\n  If you want to clean the files history for all files and only preserve the newest file version, you can use\n  \n  ```bash\n  sudo -u www-data php occ versions:cleanup\n  ```\n  Read more about this in the [docs](https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/occ_command.html?#versions).\n\n## Used libraries \u0026 components\n| Name | Version | Link |\n|---|---|---|\n| OCRmyPDF (commandline) | \u003e= 9.6.0 | https://github.com/jbarlow83/OCRmyPDF On Debian, you might need to manually install a more recent version as described in https://ocrmypdf.readthedocs.io/en/latest/installation.html#ubuntu-18-04-lts; see https://github.com/R0Wi/workflow_ocr/issues/46 |\n| php-shellcommand | \u003e= 1.6 | https://github.com/mikehaertl/php-shellcommand |\n| chain | \u003e= 0.9.0 | https://packagist.org/packages/cocur/chain |\n| PHPUnit | \u003e= 8.0 | https://phpunit.de/ |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr0wi-dev%2Fworkflow_ocr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr0wi-dev%2Fworkflow_ocr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr0wi-dev%2Fworkflow_ocr/lists"}