Add custom KiCad autocomplete list settings (#1342)

* Add admin editor for KiCad autocomplete lists

* Add custom KiCad autocomplete list settings

* Ignore the footprints_custom.txt and symbols_custom.txt in git and create them on the fly if needed

Otherwise it breaks the update mechanism

* Added comments

* Include kicad custom files in config backup command

---------

Co-authored-by: Jan Böhmer <mail@jan-boehmer.de>

src/Command/BackupCommand.php

@@ -201,6 +201,10 @@ class BackupCommand extends Command
         $config_dir = $this->project_dir.'/config';
         $zip->addFile($config_dir.'/parameters.yaml', 'config/parameters.yaml');
         $zip->addFile($config_dir.'/banner.md', 'config/banner.md');
+
+        //Add kicad custom footprints and symbols files
+        $zip->addFile($this->project_dir . '/public/kicad/footprints_custom.txt', 'public/kicad/footprints_custom.txt');
+        $zip->addFile($this->project_dir . '/public/kicad/symbols_custom.txt', 'public/kicad/symbols_custom.txt');
     }
 
     protected function backupAttachments(ZipFile $zip, SymfonyStyle $io): void

src/Controller/KicadListEditorController.php

@@ -0,0 +1,88 @@
+<?php
+/*
+ * This file is part of Part-DB (https://github.com/Part-DB/Part-DB-symfony).
+ *
+ *  Copyright (C) 2019 - 2024 Jan Böhmer (https://github.com/jbtronics)
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Affero General Public License as published
+ *  by the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Affero General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Affero General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+declare(strict_types=1);
+
+namespace App\Controller;
+
+use App\Form\Settings\KicadListEditorType;
+use App\Settings\MiscSettings\KiCadEDASettings;
+use App\Services\EDA\KicadListFileManager;
+use Jbtronics\SettingsBundle\Exception\SettingsNotValidException;
+use Jbtronics\SettingsBundle\Manager\SettingsManagerInterface;
+use RuntimeException;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Routing\Attribute\Route;
+
+use function Symfony\Component\Translation\t;
+
+final class KicadListEditorController extends AbstractController
+{
+    public function __construct(
+        private readonly SettingsManagerInterface $settingsManager,
+    ) {
+    }
+
+    #[Route('/settings/misc/kicad-lists', name: 'settings_kicad_lists')]
+    public function __invoke(Request $request, KicadListFileManager $fileManager): Response
+    {
+        $this->denyAccessUnlessGranted('IS_AUTHENTICATED_FULLY');
+        $this->denyAccessUnlessGranted('@config.change_system_settings');
+
+        /** @var KiCadEDASettings $settings */
+        $settings = $this->settingsManager->createTemporaryCopy(KiCadEDASettings::class);
+        $form = $this->createForm(KicadListEditorType::class, [
+            'useCustomList' => $settings->useCustomList,
+            'customFootprints' => $fileManager->getCustomFootprintsContent(),
+            'customSymbols' => $fileManager->getCustomSymbolsContent(),
+        ], [
+            'default_footprints' => $fileManager->getFootprintsContent(),
+            'default_symbols' => $fileManager->getSymbolsContent(),
+        ]);
+
+        $form->handleRequest($request);
+
+        if ($form->isSubmitted() && $form->isValid()) {
+            $data = $form->getData();
+
+            try {
+                $fileManager->saveCustom($data['customFootprints'], $data['customSymbols']);
+                $settings->useCustomList = (bool) $data['useCustomList'];
+                $this->settingsManager->mergeTemporaryCopy($settings);
+                $this->settingsManager->save($settings);
+                $this->addFlash('success', t('settings.flash.saved'));
+
+                return $this->redirectToRoute('settings_kicad_lists');
+            } catch (RuntimeException|SettingsNotValidException $exception) {
+                $this->addFlash('error', $exception->getMessage());
+            }
+        }
+
+        if ($form->isSubmitted() && !$form->isValid()) {
+            $this->addFlash('error', t('settings.flash.invalid'));
+        }
+
+        return $this->render('settings/kicad_list_editor.html.twig', [
+            'form' => $form,
+        ]);
+    }
+}

src/Form/Part/EDA/KicadFieldAutocompleteType.php

@@ -24,6 +24,7 @@ declare(strict_types=1);
 namespace App\Form\Part\EDA;
 
 use App\Form\Type\StaticFileAutocompleteType;
+use App\Settings\MiscSettings\KiCadEDASettings;
 use Symfony\Component\Form\AbstractType;
 use Symfony\Component\OptionsResolver\Options;
 use Symfony\Component\OptionsResolver\OptionsResolver;
@@ -39,6 +40,13 @@ class KicadFieldAutocompleteType extends AbstractType
     //Do not use a leading slash here! otherwise it will not work under prefixed reverse proxies
     public const FOOTPRINT_PATH = 'kicad/footprints.txt';
     public const SYMBOL_PATH = 'kicad/symbols.txt';
+    public const CUSTOM_FOOTPRINT_PATH = 'kicad/footprints_custom.txt';
+    public const CUSTOM_SYMBOL_PATH = 'kicad/symbols_custom.txt';
+
+    public function __construct(
+        private readonly KiCadEDASettings $kiCadEDASettings,
+    ) {
+    }
 
     public function configureOptions(OptionsResolver $resolver): void
     {
@@ -47,8 +55,8 @@ class KicadFieldAutocompleteType extends AbstractType
 
         $resolver->setDefaults([
             'file' => fn(Options $options) => match ($options['type']) {
-                self::TYPE_FOOTPRINT => self::FOOTPRINT_PATH,
-                self::TYPE_SYMBOL => self::SYMBOL_PATH,
+                self::TYPE_FOOTPRINT => $this->kiCadEDASettings->useCustomList ? self::CUSTOM_FOOTPRINT_PATH : self::FOOTPRINT_PATH,
+                self::TYPE_SYMBOL => $this->kiCadEDASettings->useCustomList ? self::CUSTOM_SYMBOL_PATH : self::SYMBOL_PATH,
                 default => throw new \InvalidArgumentException('Invalid type'),
             }
         ]);
@@ -58,4 +66,4 @@ class KicadFieldAutocompleteType extends AbstractType
     {
         return StaticFileAutocompleteType::class;
     }
-}
+}

src/Form/Settings/KicadListEditorType.php

@@ -0,0 +1,103 @@
+<?php
+/*
+ * This file is part of Part-DB (https://github.com/Part-DB/Part-DB-symfony).
+ *
+ *  Copyright (C) 2019 - 2024 Jan Böhmer (https://github.com/jbtronics)
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Affero General Public License as published
+ *  by the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Affero General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Affero General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+declare(strict_types=1);
+
+namespace App\Form\Settings;
+
+use Symfony\Component\Form\AbstractType;
+use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
+use Symfony\Component\Form\Extension\Core\Type\SubmitType;
+use Symfony\Component\Form\Extension\Core\Type\TextareaType;
+use Symfony\Component\Form\FormBuilderInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
+
+/**
+ * Form type for editing the custom KiCad footprints and symbols lists.
+ */
+final class KicadListEditorType extends AbstractType
+{
+    public function buildForm(FormBuilderInterface $builder, array $options): void
+    {
+        $builder
+            ->add('useCustomList', CheckboxType::class, [
+                'label' => 'settings.misc.kicad_eda.use_custom_list',
+                'help' => 'settings.misc.kicad_eda.use_custom_list.help',
+                'required' => false,
+            ])
+            ->add('customFootprints', TextareaType::class, [
+                'label' => 'settings.misc.kicad_eda.editor.custom_footprints',
+                'help' => 'settings.misc.kicad_eda.editor.footprints.help',
+                'attr' => [
+                    'rows' => 16,
+                    'spellcheck' => 'false',
+                    'class' => 'font-monospace',
+                ],
+            ])
+            ->add('defaultFootprints', TextareaType::class, [
+                'label' => 'settings.misc.kicad_eda.editor.default_footprints',
+                'help' => 'settings.misc.kicad_eda.editor.default_files_help',
+                'disabled' => true,
+                'mapped' => false,
+                'data' => $options['default_footprints'],
+                'attr' => [
+                    'rows' => 16,
+                    'spellcheck' => 'false',
+                    'class' => 'font-monospace',
+                    'readonly' => 'readonly',
+                ],
+            ])
+            ->add('customSymbols', TextareaType::class, [
+                'label' => 'settings.misc.kicad_eda.editor.custom_symbols',
+                'help' => 'settings.misc.kicad_eda.editor.symbols.help',
+                'attr' => [
+                    'rows' => 16,
+                    'spellcheck' => 'false',
+                    'class' => 'font-monospace',
+                ],
+            ])
+            ->add('defaultSymbols', TextareaType::class, [
+                'label' => 'settings.misc.kicad_eda.editor.default_symbols',
+                'help' => 'settings.misc.kicad_eda.editor.default_files_help',
+                'disabled' => true,
+                'mapped' => false,
+                'data' => $options['default_symbols'],
+                'attr' => [
+                    'rows' => 16,
+                    'spellcheck' => 'false',
+                    'class' => 'font-monospace',
+                    'readonly' => 'readonly',
+                ],
+            ])
+            ->add('save', SubmitType::class, [
+                'label' => 'save',
+            ]);
+    }
+
+    public function configureOptions(OptionsResolver $resolver): void
+    {
+        $resolver->setDefaults([
+            'default_footprints' => '',
+            'default_symbols' => '',
+        ]);
+        $resolver->setAllowedTypes('default_footprints', 'string');
+        $resolver->setAllowedTypes('default_symbols', 'string');
+    }
+}

src/Services/EDA/KicadListFileManager.php

@@ -0,0 +1,158 @@
+<?php
+/*
+ * This file is part of Part-DB (https://github.com/Part-DB/Part-DB-symfony).
+ *
+ *  Copyright (C) 2019 - 2024 Jan Böhmer (https://github.com/jbtronics)
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Affero General Public License as published
+ *  by the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Affero General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Affero General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+declare(strict_types=1);
+
+namespace App\Services\EDA;
+
+use RuntimeException;
+use Symfony\Component\DependencyInjection\Attribute\Autowire;
+use Symfony\Component\HttpKernel\CacheWarmer\CacheWarmerInterface;
+
+/**
+ * Manages the KiCad footprints and symbols list files, including reading, writing and ensuring their existence.
+ */
+final class KicadListFileManager implements CacheWarmerInterface
+{
+    private const FOOTPRINTS_PATH = '/public/kicad/footprints.txt';
+    private const SYMBOLS_PATH = '/public/kicad/symbols.txt';
+    private const CUSTOM_FOOTPRINTS_PATH = '/public/kicad/footprints_custom.txt';
+    private const CUSTOM_SYMBOLS_PATH = '/public/kicad/symbols_custom.txt';
+
+    private const CUSTOM_TEMPLATE = <<<'EOT'
+        # Custom KiCad autocomplete entries. One entry per line.
+
+        EOT;
+
+    public function __construct(
+        #[Autowire('%kernel.project_dir%')]
+        private readonly string $projectDir,
+    ) {
+    }
+
+    public function getFootprintsContent(): string
+    {
+        return $this->readFile(self::FOOTPRINTS_PATH);
+    }
+
+    public function getCustomFootprintsContent(): string
+    {
+        //Ensure that the custom file exists, so that the UI can always display it without error.
+        $this->createCustomFileIfNotExists(self::CUSTOM_FOOTPRINTS_PATH);
+        return $this->readFile(self::CUSTOM_FOOTPRINTS_PATH);
+    }
+
+    public function getSymbolsContent(): string
+    {
+        return $this->readFile(self::SYMBOLS_PATH);
+    }
+
+    public function getCustomSymbolsContent(): string
+    {
+        //Ensure that the custom file exists, so that the UI can always display it without error.
+        $this->createCustomFileIfNotExists(self::CUSTOM_SYMBOLS_PATH);
+        return $this->readFile(self::CUSTOM_SYMBOLS_PATH);
+    }
+
+    public function saveCustom(string $footprints, string $symbols): void
+    {
+        $this->writeFile(self::CUSTOM_FOOTPRINTS_PATH, $this->normalizeContent($footprints));
+        $this->writeFile(self::CUSTOM_SYMBOLS_PATH, $this->normalizeContent($symbols));
+    }
+
+    private function readFile(string $path): string
+    {
+        $fullPath = $this->projectDir . $path;
+
+        if (!is_file($fullPath)) {
+            return '';
+        }
+
+        $content = file_get_contents($fullPath);
+        if ($content === false) {
+            throw new RuntimeException(sprintf('Failed to read KiCad list file "%s".', $fullPath));
+        }
+
+        return $content;
+    }
+
+    private function writeFile(string $path, string $content): void
+    {
+        $fullPath = $this->projectDir . $path;
+        $tmpPath = $fullPath . '.tmp';
+
+        if (file_put_contents($tmpPath, $content, LOCK_EX) === false) {
+            throw new RuntimeException(sprintf('Failed to write KiCad list file "%s".', $fullPath));
+        }
+
+        if (!rename($tmpPath, $fullPath)) {
+            @unlink($tmpPath);
+            throw new RuntimeException(sprintf('Failed to replace KiCad list file "%s".', $fullPath));
+        }
+    }
+
+    private function normalizeContent(string $content): string
+    {
+        $normalized = str_replace(["\r\n", "\r"], "\n", $content);
+
+        if ($normalized !== '' && !str_ends_with($normalized, "\n")) {
+            $normalized .= "\n";
+        }
+
+        return $normalized;
+    }
+
+    private function createCustomFileIfNotExists(string $path): void
+    {
+        $fullPath = $this->projectDir . $path;
+
+        if (!is_file($fullPath)) {
+            if (file_put_contents($fullPath, self::CUSTOM_TEMPLATE, LOCK_EX) === false) {
+                throw new RuntimeException(sprintf('Failed to create custom footprints file "%s".', $fullPath));
+            }
+        }
+    }
+
+    /**
+     * Ensures that the custom footprints and symbols files exist, so that the UI can always display them without error.
+     * @return void
+     */
+    public function createCustomFilesIfNotExist(): void
+    {
+        $this->createCustomFileIfNotExists(self::CUSTOM_FOOTPRINTS_PATH);
+        $this->createCustomFileIfNotExists(self::CUSTOM_SYMBOLS_PATH);
+    }
+
+
+    public function isOptional(): bool
+    {
+        return false;
+    }
+
+    /**
+     * Ensure that the custom footprints and symbols files exist and generate them on cache warmup, so that the frontend
+     * can always display them without error, even if the user has not yet visited the settings page.
+     */
+    public function warmUp(string $cacheDir, ?string $buildDir = null): array
+    {
+        $this->createCustomFilesIfNotExist();
+        return [];
+    }
+}

src/Settings/MiscSettings/KiCadEDASettings.php

@@ -62,4 +62,10 @@ class KiCadEDASettings
 
     )]
     public bool $defaultOrderdetailsVisibility = false;
+
+    #[SettingsParameter(
+        label: new TM("settings.misc.kicad_eda.use_custom_list"),
+        description: new TM("settings.misc.kicad_eda.use_custom_list.help"),
+    )]
+    public bool $useCustomList = false;
 }