{"id":23127884,"url":"https://github.com/ujamii/openimmo","last_synced_at":"2025-10-03T14:40:20.080Z","repository":{"id":34079112,"uuid":"167570565","full_name":"ujamii/openimmo","owner":"ujamii","description":"OpenImmo library","archived":false,"fork":false,"pushed_at":"2025-09-05T13:25:25.000Z","size":795,"stargazers_count":47,"open_issues_count":4,"forks_count":15,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-09-08T17:39:05.753Z","etag":null,"topics":["api","code-generator","composer","composer-package","openimmo","xsd","xsd-converter"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ujamii.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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,"zenodo":null},"funding":{"github":"mgrundkoetter"}},"created_at":"2019-01-25T15:40:40.000Z","updated_at":"2025-09-05T13:25:29.000Z","dependencies_parsed_at":"2024-03-06T14:48:08.997Z","dependency_job_id":"9e0f37ff-b1fc-4403-aa80-c1343c3f41c7","html_url":"https://github.com/ujamii/openimmo","commit_stats":{"total_commits":223,"total_committers":5,"mean_commits":44.6,"dds":"0.19730941704035876","last_synced_commit":"991ca1a7744441ac05c3074d68718c085472666f"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/ujamii/openimmo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ujamii%2Fopenimmo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ujamii%2Fopenimmo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ujamii%2Fopenimmo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ujamii%2Fopenimmo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ujamii","download_url":"https://codeload.github.com/ujamii/openimmo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ujamii%2Fopenimmo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278176621,"owners_count":25942933,"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","status":"online","status_checked_at":"2025-10-03T02:00:06.070Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["api","code-generator","composer","composer-package","openimmo","xsd","xsd-converter"],"created_at":"2024-12-17T09:15:32.036Z","updated_at":"2025-10-03T14:40:20.075Z","avatar_url":"https://github.com/ujamii.png","language":"PHP","funding_links":["https://github.com/sponsors/mgrundkoetter"],"categories":[],"sub_categories":[],"readme":"# OpenImmo PHP library\n\n[![Packagist](https://img.shields.io/packagist/v/ujamii/openimmo.svg?colorB=green\u0026style=flat)](https://packagist.org/packages/ujamii/openimmo)\n[![Minimum PHP Version](https://img.shields.io/badge/php-8.1%2B-8892BF.svg?style=flat)](https://php.net/)\n[![Continuous Integration](https://github.com/ujamii/openimmo/actions/workflows/php.yml/badge.svg)](https://github.com/ujamii/openimmo/actions)\n[![codecov](https://codecov.io/gh/ujamii/openimmo/branch/master/graph/badge.svg?token=97D799UX1B)](https://codecov.io/gh/ujamii/openimmo)\n[![Mutation testing badge](https://img.shields.io/endpoint?style=flat\u0026url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fujamii%2Fopenimmo%2Fmaster)](https://dashboard.stryker-mutator.io/reports/github.com/ujamii/openimmo/master)\n\nOpenImmo and the OpenImmo logo are registered trademarks of the [OpenImmo e.V.](http://www.openimmo.de)\nNeither is this package an official distribution nor am I associated with this organisation!\n\nThis library just wraps the OpenImmo XML format with some PHP8 classes.\nIf you need support for PHP \u003c= 8.1, see version 1.x of this package. Version 2 is for PHP \u003e=8.2 only.\n\nThere is an official library available at http://www.openimmo.de/go.php/p/22/support20.htm which costs 95 EUR excl. VAT and is \n\"compatible with PHP5 and tested with PHP 8.1\" (end quote).\nTo completely convince you, you will only be allowed to see the code **after** you have paid and they have a no-refund policy. \n\n**Important notes**\n\n1. I don't want to include **real world xml examples** into this distribution package due to possible license and privacy issues. Thus, some tests are automatically\nskipped, if the xml files are not found in the examples directory!\nThe \"Open\" in OpenImmo has nothing to do with Open Source (I have been told via email).\n\n1. From a software architecture point of view, using the **German names** for everything in the codebase feels bad for every developer, I know. I feel the same. \nAnd I still use the German labels in the codebase nevertheless. Simple reason: I value maintainability and readability more than sticking to the rules no matter what.\nSo to be consistent in names for properties, classes and with xml/xsd properties and to make it easy to actually know what you're talking about when debugging this project,\nI decided to take the burden of using German names but I think it is worth it.\n\n1. Also, dealing with this kind of data is probably done in more complex and big projects than in small and very agile ones, I suppose. Hence I actively chose not to\nbe **cutting edge** with all the fancy features new PHP versions provide. I will maintain the currently supported [PHP versions](https://www.php.net/supported-versions.php)\nbecause I assume those type of projects have some more compatibility constraints to match and I don's want to bring another tight requirement in with this library.\nI you deeply want to have all the modern things in here, feel free to fork and open a PR, so everyone can benefit from it. You're very welcome!\n\n## TODOs\n\n- add test cases, especially for the example file provided with the official download package.\n\n## Installation\n\n```shell\ncomposer req ujamii/openimmo\n```\n\n## Integrations\n\nIf you like to use this API as base for an integration into a CMS or Framework, feel free to contact me, I will link it here.\n\n- Integration into TYPO3 CMS, [extension \"openimmo\"](https://github.com/ujamii/openimmo-typo3)\n- NEOS CMS, [package \"Ujamii.OpenImmoNeos\"](https://github.com/ujamii/openimmo-neos)\n- [Laravel-Package](https://github.com/innobraingmbh/laravel-openimmo)\n\n## Usage\n\n### Writing OpenImmo XML\n\n```php\n// just create the elements you need in your xml and use the set-methods to fill in values.\n$nutzungsart = new Nutzungsart();\n$nutzungsart\n    -\u003esetWohnen(true)\n    -\u003esetGewerbe(false)\n    -\u003esetAnlage(false)\n    -\u003esetWaz(false);\n\n$serializer = \\JMS\\Serializer\\SerializerBuilder::create()-\u003ebuild();\necho $serializer-\u003eserialize($nutzungsart, 'xml');\n```\n\nwill produce\n\n```xml\n\u003cnutzungsart WOHNEN=\"true\" GEWERBE=\"false\" ANLAGE=\"false\" WAZ=\"false\" /\u003e\n```\n\nNested elements are created just as easy. Classes, properties, constants and parameters are named as corresponding items in the xsd file.\nThey are just converted to camelCase to comply with PHP standards.\n\n```php\n$infrastrktur = new Infrastruktur();\n$infrastrktur\n    -\u003esetZulieferung(false)\n    -\u003esetAusblick((new Ausblick())-\u003esetBlick(Ausblick::BLICK_BERGE))\n    -\u003esetDistanzenSport([\n        new DistanzenSport(DistanzenSport::DISTANZ_ZU_SPORT_SEE, 15)\n    ])\n    -\u003esetDistanzen([\n        new Distanzen(Distanzen::DISTANZ_ZU_HAUPTSCHULE, 22)\n    ]);\n    \n$serializer = \\JMS\\Serializer\\SerializerBuilder::create()-\u003ebuild();\necho $serializer-\u003eserialize($infrastrktur, 'xml');\n```\n\nwill generate\n\n```xml\n\u003cinfrastruktur\u003e\n\t\u003causblick blick=\"BERGE\" /\u003e\n\t\u003cdistanzen distanz_zu=\"HAUPTSCHULE\" \u003e22.0\u003c/distanzen\u003e\n\t\u003cdistanzen_sport distanz_zu_sport=\"SEE\" \u003e15.0\u003c/distanzen_sport\u003e\n\t\u003czulieferung\u003efalse\u003c/zulieferung\u003e\n\u003c/infrastruktur\u003e\n```\n\n### Reading OpenImmo XML\n\nReading data from xml into a easy-to-use object structure is also pretty straightforward. This example will generate a list of\nobjects (addresses).\n\n```php\n$xmlString = file_get_contents('./example/foobar.xml');\n/* @var $openImmo \\Ujamii\\OpenImmo\\API\\Openimmo */\n$openImmo = $serializer-\u003edeserialize($xmlString, \\Ujamii\\OpenImmo\\API\\Openimmo::class, 'xml');\n\n/* @var $anbieter \\Ujamii\\OpenImmo\\API\\Anbieter */\nforeach ($openImmo-\u003egetAnbieter() as $anbieter) {\n    /* @var $immobilie \\Ujamii\\OpenImmo\\API\\Immobilie */\n    foreach ($anbieter-\u003egetImmobilie() as $immobilie) {\n        echo PHP_EOL . vsprintf('%s %s, %s %s', [\n                $immobilie-\u003egetGeo()-\u003egetStrasse(),\n                $immobilie-\u003egetGeo()-\u003egetHausnummer(),\n                $immobilie-\u003egetGeo()-\u003egetPlz(),\n                $immobilie-\u003egetGeo()-\u003egetOrt(),\n            ]);\n    }\n}\n```\n\n### Writing JSON (since v0.10)\n\nAlthough the OpenImmo standard just describes an XML version, there may be cases when you want to generate JSON from the given data.\nSadly, there is [an issue](https://github.com/schmittjoh/serializer/issues/1251) with custom types, scalar values and JSON serialization in the JMS serializer.\nHowever, it is still possible to write JSON format with the [Symfony serializer component](https://symfony.com/doc/current/components/serializer.html).\n\n```shell\ncomposer require symfony/serializer\n```\n\nGenerating JSON then works like this:\n\n```php\nuse Symfony\\Component\\Serializer\\Encoder\\JsonEncoder;\nuse Symfony\\Component\\Serializer\\Normalizer\\AbstractObjectNormalizer;\nuse Symfony\\Component\\Serializer\\Normalizer\\DateTimeNormalizer;\nuse Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer;\nuse Symfony\\Component\\Serializer\\Serializer;\n\n$openImmoObject = null; // this may be any object of one of the API classes from this package\n$encoders    = [new JsonEncoder()];\n$normalizers = [\n    new DateTimeNormalizer(),\n    new GetSetMethodNormalizer()\n];\n$serializerContext = [\n    AbstractObjectNormalizer::SKIP_NULL_VALUES       =\u003e true,\n    AbstractObjectNormalizer::PRESERVE_EMPTY_OBJECTS =\u003e false,\n    'json_encode_options'                            =\u003e \\JSON_PRESERVE_ZERO_FRACTION\n];\n\n$serializer = new Serializer($normalizers, $encoders);\n$jsonContent = $this-\u003eserializer-\u003eserialize($openImmoObject, JsonEncoder::FORMAT, $serializerContext);\n```\n\n### Possible issues\n\n#### DateTime format not working\n\nSome tools may generate DateTime values in the xml, which cause errors like\n\n```\nFatal error: Uncaught JMS\\Serializer\\Exception\\RuntimeException: Invalid datetime \"2020-08-07T11:56:39.1242974+02:00\", expected one of the format \"Y-m-d\\TH:i:sP\", \"Y-m-d\\TH:i:s\".\n```\n\nThis can be caused by a different precision for the microsecond part (1242974) of this value. As the default PHP precision may be lower\nthat the one of the tool, which the xml was generated with. If this problem occurs with the data you use, you can add a handler, included\nin this package, to the serializer like this:\n\n```php\nuse JMS\\Serializer\\Handler\\HandlerRegistryInterface;\nuse Ujamii\\OpenImmo\\Handler\\DateTimeHandler;\n\n$builder = \\JMS\\Serializer\\SerializerBuilder::create();\n$builder\n    -\u003econfigureHandlers(function(HandlerRegistryInterface $registry) {\n        $registry-\u003eregisterSubscribingHandler(new DateTimeHandler());\n    })\n;\n$serializer = $builder-\u003ebuild();\n```\n\n### Update API classes with a new OpenImmo version \n\n1. Install composer package.\n2. Download OpenImmo files from [their website](http://www.openimmo.de/go.php/p/24/download.htm) (extract into the example folder). Their license agreement denies redistribution of the xsd file.\n3. `php -f generate-api.php` will fill the `src/API` directory with new classes.\n4. `composer dumpautoload` to update the autoloading.\n5. Done.\n\n### Running tests\n\n1. `composer run phpunit`\n\n## License and Contribution\n\n[GPLv3](LICENSE)\n\nAs this is OpenSource, you are very welcome to contribute by reporting bugs, improve the code, write tests or \nwhatever you are able to do to improve the project.\n\nIf you want to do me a favour, buy me something from my [Amazon wishlist](https://www.amazon.de/registry/wishlist/2C7LSRMLEAD4F).\n\n### Thank you!\n\n- [Qbus Internetagentur GmbH](https://www.qbus.de/) for your code contribution\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fujamii%2Fopenimmo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fujamii%2Fopenimmo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fujamii%2Fopenimmo/lists"}